melaya 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1dac0d815408d37da57f6288caec96ebd16db731405ae977759211cba627ac0
-  data.tar.gz: adc032f6a8446ae788f0c4288b0b14d755288c92c50cd10cd5400dd8874dad74
+  metadata.gz: 47fefbce18553e5a38d414eb96ad35da805b1bb4d685e9fd809206b00d2dbe68
+  data.tar.gz: 822418410f53fc0cb03caf2fd06a8a122db8082e58ded4c68f6032dea5898965
 SHA512:
-  metadata.gz: 6088333696eec5b43ec4d917477b4afd628f136507d2b492f4d50d540836645aaf76e7bbc2427fa19bca2ed05a5444a148d9b189a8c4a04b4a257d8536a9a777
-  data.tar.gz: 1c2e6cb42d6a23940c49a1b0fbd7a07160416923584541106b2a11935a9ca67bf16f6b18561d8f1099a4be7b3b70e3e93a7eb0f31ee4b5e298325635ad74ab3e
+  metadata.gz: 7680af7ede9b7cfa4e4fa2c6860c3e40260c488f2a3b6906930382b9a44ab36862ff8117ac6ce533bcac5fe5d7b8f12c4961257a61c149ebf6c07953da84e1e7
+  data.tar.gz: 6e929c21c54d44b99c0cfffa1d717ca85ca95bf0c95ecbc1d2e260e9343e8cc4383d47e38d7b9ffe965aa15798e7ee202ae2230f2fc4de75a21b15bdd2aa500e

data/LICENSE

@@ -0,0 +1,158 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+      PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer, and
+      charge a fee for, acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Melaya (Antoine Roche)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,10 +1,15 @@
 # melaya
 
-Official Ruby SDK for the **[Melaya](https://melaya.org)** trading platform — normalized market data, paper + live trading, backtesting, and an AI agentic trading crew across **70+ venues**, powered by an in-house Rust engine.
+> **Current production scope:** Agent Builder and Mobile Device Control are available now. Melaya Trading namespaces are preview-only and not generally available; do not use them with real funds.
+
+Official SDK for the **[Melaya](https://melaya.org)** Agent Builder and flagship Mobile Device Control APIs. Trading namespaces are included only as a preview of a later product.
+
+**Melaya products:** [Melaya Agents](https://melaya.org/en/product/agentic-framework) · [Melaya Assistant](https://melaya.org/en/product/assistant) · [Device Control](https://melaya.org/en/product/agentic-device-control) · [Browser Control](https://melaya.org/en/product/agentic-browser-control) · [MCP Server](https://melaya.org/en/product/mcp) · [Melaya Marketing](https://melaya.org/en/product/marketing)
 
 - Zero runtime gem dependencies (stdlib `net/http`, `openssl`, `json` only).
+- Full Agent Builder lifecycle: projects, pipelines, templates, Connectors, HITL, evals, events, billing, team, and runner management.
+- Catalogs of **1,500+ scoped tools**, **100+ specialized subagents**, and **20+ model providers** (runtime catalog endpoints are the source of truth).
 - Pure Ruby WebSocket client (RFC 6455) — no external gem required for streaming.
-- Full market data, strategies, sim trading, backtesting, and streaming from one client.
 
 ## Install
 
@@ -20,7 +25,128 @@ Or once published to RubyGems:
 gem install melaya
 ```
 
-## Quick start
+## Agent Builder & Device Control
+
+### Quick start: pair a phone
+
+```ruby
+require "melaya"
+
+melaya = Melaya::Client.new(api_key: ENV["MELAYA_API_KEY"])  # keys are prefixed mk_
+
+pairing = melaya.agents.phone.pair
+puts "Pairing code: #{pairing["code"]} (expires in #{pairing["expiresInSeconds"]}s)"
+# Enter the code in the Melaya APK on the phone
+
+devices = melaya.agents.phone.list_devices
+apps    = melaya.agents.phone.list_apps
+
+melaya.agents.phone.set_allowed_apps(["com.android.chrome"])
+```
+
+A Melaya platform key is required. "No app API required" means Device Control operates the target app through its user interface; it does not mean the Melaya SDK is unauthenticated.
+
+### Quick start: run an agent pipeline
+
+Configure provider credentials through Melaya Connectors first. Never include a provider key in pipeline configuration or per-run overrides.
+
+A pipeline's run is generated **only** from `config["steps"]` — a top-level `agents` list alone produces an **empty** pipeline. Every agent a step runs must be embedded inline on that step's `"agent"` key. There is no `prompt` field: the two prompt fields are `instruction` (the task) and, optionally, `system_prompt_override`.
+
+```ruby
+melaya.agents.pipelines.create(
+  name:    "mobile-review",
+  project: "Operations",
+  steps: [{
+    "kind"  => "agent",
+    "agent" => {
+      "name"        => "mobile-operator",
+      "role"        => "Careful mobile operator",
+      "instruction" => "Read before acting. Never send, publish, or delete.",
+      "model"       => { "provider" => "anthropic", "name" => "claude-sonnet-4-6" },
+      "agent_tools" => [
+        "phone_get_screen_tree",
+        "phone_current_app",
+        "phone_open_app",
+        "phone_click_text",
+        "phone_back",
+        "phone_wait"
+      ],
+      "human_approval_tools" => []
+    }
+  }],
+  maxCostUsd: 1.00
+)
+
+run    = melaya.agents.pipelines.run("mobile-review", project: "Operations")
+run_id = run["run_id"]
+
+melaya.agents.phone.register_active_run(run_id)
+
+status = melaya.agents.pipelines.run_status("mobile-review", run_id)
+
+# Real-time run events over Socket.IO (connects lazily on first use)
+melaya.events.on_run_update(run_id) { |e| puts e["event_type"] }
+```
+
+Other config fields worth knowing: `"hitl_mode"` (`"safe"` default | `"autonomous"` | `"payments_only"` — only `"safe"` honours each agent's `human_approval_tools`), `"connector_source"` (`"personal"` | `"project"`), `"force_local_runner"`, and `"inputs"` (declared run-input fields, see `run_inputs:` below).
+
+`get` returns an **envelope**, not a bare config — `{ "name", "client", "config", "code", "docs" }`. To edit and save, mutate `envelope["config"]` and pass that to `update`:
+
+```ruby
+envelope = melaya.pipelines.get("mobile-review", project: "Operations")
+config   = envelope["config"]
+config["steps"][0]["agent"]["model"] = { "provider" => "anthropic", "name" => "claude-opus-4-8" }
+melaya.pipelines.update("mobile-review", config: config, project: "Operations")
+```
+
+### Quick start: run inputs and file attachments
+
+```ruby
+# Upload a file ahead of a run, then reference it by file_id
+upload = melaya.pipelines.upload_run_file("mobile-review", "screenshot", File.open("shot.png", "rb"))
+
+run = melaya.pipelines.run("mobile-review",
+  project: "Operations",
+  run_inputs: {
+    "brief"  => "Review the attached screenshot for policy violations.",
+    "values" => { "screenshot" => { "file_id" => upload["file_id"] } }
+  }
+)
+
+# Download a run's own input file back (raw bytes — do not JSON-parse)
+bytes = melaya.pipelines.run_input_file("mobile-review", run["run_id"], 0)
+```
+
+### Quick start: call a connector tool directly
+
+Call any of your already-connected service tools (Gmail, Slack, Stripe, ...) —
+the same surface the MCP server and the Melaya Assistant use. This is
+different from `melaya.connectors`, which only stores project credentials.
+
+Reads run immediately. Writes default to `approval: "required"`, which stages
+the same approval card the Assistant raises in the Melaya app and returns
+HTTP 202 (a success, not an error) with a `requestId` to poll; pass
+`approval: "none"` to run a write immediately instead (still audit-logged).
+Money-moving/trading tools are always refused, under both approval modes. No
+method here ever accepts or returns a credential value.
+
+```ruby
+melaya.agents.connector_tools.services                      # { "services" => [...], "toolCounts" => {...} }
+melaya.agents.connector_tools.search("unread email")        # discover tools by keyword
+melaya.agents.connector_tools.describe("gmail_list_messages")
+
+# Read — runs immediately
+result = melaya.agents.connector_tools.call("gmail_list_messages", args: { max_results: 5 })
+puts result["result"]
+
+# Write — staged for approval by default; block until decided (or it 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
+```
+
+## Trading quick start (preview)
 
 ```ruby
 require "melaya"
@@ -38,7 +164,7 @@ ob = melaya.market.orderbook(exchange: "bybit", symbol: "BTC/USDT", market: "spo
 candles = melaya.market.ohlcv(exchange: "okx", symbol: "ETH/USDT", timeframe: "1h", limit: 200)
 ```
 
-## Streaming
+## Streaming (preview)
 
 ```ruby
 # Live ticker (block form — closes when block returns)
@@ -54,7 +180,7 @@ melaya.stream.liquidations(exchange: "binance") do |ev|
 end
 ```
 
-## Trading
+## Trading (preview)
 
 ```ruby
 # Account: connected exchange keys and usage
@@ -126,21 +252,43 @@ melaya.strategies.delete(sid)
 
 ## Authentication
 
-Create an API key in the dashboard (**melaya.org → Settings → API Keys**). Keys are prefixed `mk_`; the SDK sends it automatically on every REST call and WebSocket connection.
+Create an API key in the dashboard (**melaya.org → Settings → API Keys**). Keys are prefixed `mk_`. Every REST call sends the key **only** as an `Authorization: Bearer mk_...` header — never in the URL query string. Public WebSocket market-data streams authenticate with `?apiKey=` in the `wss://` URL (server protocol); private WebSocket streams instead use a short-lived `?wsTicket=` that the SDK mints automatically.
 
 Public market-data and account/strategy reads work with the `mk_` key alone. **Live** order placement and live strategy launches additionally require a connected exchange key — connect one in **Settings → Connectors**, then reference it by `apiKeyId`. Paper trading and backtesting never touch a venue and need no exchange credentials.
 
-## TLS verification
-
-The SDK verifies TLS certificates by default. To disable on a dev box with TLS interception:
-
-```bash
-MELAYA_INSECURE_TLS=1 ruby your_script.rb
-```
+## API surface
 
-Or pass `verify_ssl: false` to the constructor. **Never disable TLS in production.**
+### Agent Builder & platform (GA)
 
-## API surface
+| Area | Methods |
+|---|---|
+| Auth | `auth.login`, `verify_mfa`, `register`, `verify_signup`, `resend_verification`, `me`, `check`, `change_password`, `forgot_password`, `reset_password`, `mobile_handoff`, `permissions`, `refresh` |
+| MFA | `auth.mfa_status`, `mfa_setup`, `mfa_confirm` (also via `melaya.platform.mfa`) |
+| Projects | `projects.list`, `create`, `rename`, `runner_projects` |
+| Connectors | `connectors.connected_services`, `set`, `delete`, `env_handle`, `google_oauth_start`, `apply_personal`, `shared_by`, `google_status`, `google_set_default`, `google_disconnect`, `db_test_start`, `db_test_status` |
+| Connector Tools | `connector_tools.services`, `search`, `describe`, `test`, `connect`, `call`, `call_status`, `call_and_wait` |
+| Credentials | `credentials.list`, `connected_services`, `get`, `set`, `delete`, `test`, `list_models`, `google_status`, `google_set_default`, `google_disconnect`, `db_test_start`, `db_test_status`, `telegram_qr_start`, `telegram_qr_poll`, `whatsapp_signup_config`, `whatsapp_signup_exchange`, `tiktok_creator_info`, `substack_email_link_send`, `substack_email_link_redeem`, plus operator-profile, OAuth, and RAG helpers |
+| Pipelines | `pipelines.create`, `get`, `update`, `delete_pipeline`, `list_pipelines`, `run`, `upload_run_file`, `run_inputs`, `run_input_file`, `run_active`, `run_ids`, `run_status`, `cancel_run`, `outputs`, `output`, `preview_code`, `tools`, `subagents`, `instantiate_template`, `build_with_ai` |
+| Pipeline docs & RAG | `pipelines.list_docs`, `upload_doc`, `delete_doc`, `upload_retrieval_doc`, `ingest_retrieval`, `delete_retrieval_doc` |
+| Runs & traces | `pipelines.list`, `recent`, `count`, `traces`, `trace`, `trace_stats`, `delete_traces` |
+| Tool-call audit | `pipelines.project_tool_calls`, `project_tool_call_facets`, `tool_call_detail` |
+| Schedules | `pipelines.list_schedules`, `get_schedule`, `upsert_schedule`, `pause_schedule`, `resume_schedule` |
+| Overview | `pipelines.overview`, `model_prices`, `chart_data`, `cost_breakdown`, `server_version` |
+| Templates | `templates.list`, `list_global`, `list_validated`, `save`, `update`, `duplicate`, `delete`, `share`, `share_targets`, `list_assignments`, `assign(id, user_id:` \| `project_id:)`, `unassign(id, user_id:` \| `project_id:)` |
+| Phone | `phone.pair`, `list_devices`, `revoke_device`, `screen_tree`, `list_apps`, `set_allowed_apps`, `register_active_run`, `grant_app`, `request_cast` |
+| HITL | `hitl.pending`, `history`, `approve`, `reject`, `bulk_decide`, `run_tool_stats`, `run_tool_stats_by_agent`, `run_messages`, `run_tool_calls` |
+| Evals | `evals.list_runs`, `summary`, `run_detail`, `compare`, `memory_graph`, `run_memory`, `crew_memory`, `edit_crew_memory_entry`, `delete_crew_memory_entry`, `benchmarks` |
+| Events | `events.on_run_update`, `on_init_phase`, `on_project_event`, `on_hitl_approval`, `on_pipeline_created`, `on_pipeline_updated`, `on_pipeline_deleted`, `leave_run`, `leave_project`, `close` |
+| Billing | `billing.subscription`, `create_checkout`, `create_portal`, `plans`, `credits`, `ai_credits`, `portfolio_ideas_credits`, `risk_monitoring_credits`, `ambassador_perk`, `redeem_code`, `reserved_promo` |
+| Accounts | `accounts.export_data`, `remove_key`, `update_profile`, `resend_email_verification`, `verify_email` |
+| Runner | `runner.create_token`, `list_tokens`, `revoke_token` |
+| Team | `team.list_members`, `invite`, `create_invite_link`, `accept_invite`, `update_member_role`, `remove_member`, `transfer_ownership`, `get_pipeline_visibility`, `set_pipeline_visibility` |
+| Assistant | `assistant.get_profile`, `set_profile` |
+| Bugs | `bugs.create`, `list_mine`, `get`, `add_comment`, `list_notifications`, `mark_notifications_read` |
+
+Every area is also reachable through the domain namespaces: `melaya.agents.*` (pipelines/runs, hitl, assistant, phone, evals, models, connector_tools) and `melaya.platform.*` (projects, credentials, connectors, billing, team, templates, overview, runner, auth, mfa, accounts, bugs, events).
+
+### Trading (preview — not generally available)
 
 | Area | Methods |
 |---|---|
@@ -156,7 +304,7 @@ Or pass `verify_ssl: false` to the constructor. **Never disable TLS in productio
 | Public streaming | `stream.ticker`, `orderbook`, `ohlcv`, `trades`, `liquidations` |
 | Private streaming | `stream.strategies`, `stream.private` |
 
-Full docs: **[melaya.org/docs](https://melaya.org/docs)**.
+Full docs: **[melaya.org/documentation](https://melaya.org/documentation)**.
 
 ## License
 

data/lib/melaya/accounts.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Accounts API — GDPR data export, API key management, and profile updates.
+  #
+  # Maps to /api/v1/private/accounts/* and /api/v1/private/keys/*.
+  #
+  # Note: credit balance endpoints live in BillingAPI to keep billing concerns
+  # co-located. Key listing is in AccountAPI (trading plane) for backward
+  # compatibility; this module covers the write/management side.
+  class AccountsAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # POST /api/v1/private/accounts/export
+    # GDPR Art 15/20 data export; returns JSON blob of all user data.
+    def export_data
+      @http.post("/api/v1/private/accounts/export")
+    end
+
+    # POST /api/v1/private/accounts/resend-email-verification
+    # Send a verification email to the signed-in account's saved address.
+    def resend_email_verification
+      @http.post("/api/v1/private/accounts/resend-email-verification")
+    end
+
+    # POST /api/v1/private/accounts/verify-email
+    # Confirm saved-email ownership without creating a login session.
+    # @param token [String] 64 hex-char verification token
+    def verify_email(token)
+      @http.post("/api/v1/private/accounts/verify-email", "token" => token)
+    end
+
+    # DELETE /api/v1/private/keys/:keyId
+    # Remove a stored CEX API key.
+    # @param key_id [String]
+    def remove_key(key_id)
+      @http.delete("/api/v1/private/keys/#{enc(key_id)}")
+    end
+
+    # PATCH /api/v1/private/accounts/profile
+    # Update user display name, avatar, or settings.
+    # @param body [Hash]
+    def update_profile(body = {})
+      @http.patch("/api/v1/private/accounts/profile", body)
+    end
+
+    private
+
+    def enc(s)
+      URI.encode_www_form_component(s.to_s)
+    end
+  end
+end

data/lib/melaya/assistant.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Assistant API — get and save the caller's onboarding / persona profile.
+  #
+  # The profile is stored envelope-encrypted (service=assistant_profile) and
+  # used to personalise the in-app assistant experience.
+  #
+  # Maps to /api/v1/private/assistant/profile.
+  #
+  # @example
+  #   profile = melaya.assistant.get_profile
+  #   melaya.assistant.set_profile(name: "Antoine", goals: ["grow my trading edge"])
+  class AssistantAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # GET /api/v1/private/assistant/profile
+    # Get the caller's assistant onboarding profile.
+    def get_profile
+      @http.get("/api/v1/private/assistant/profile")
+    end
+
+    # PUT /api/v1/private/assistant/profile
+    # Save the caller's assistant onboarding profile.
+    # @param name [String, nil]
+    # @param goals [Array<String>, nil]
+    # @param context [String, nil]
+    # @param preferences [Hash, nil]
+    # @param extra [Hash] any additional profile fields
+    def set_profile(name: nil, goals: nil, context: nil, preferences: nil, **extra)
+      profile = extra.transform_keys(&:to_s)
+      profile["name"]        = name        unless name.nil?
+      profile["goals"]       = goals       unless goals.nil?
+      profile["context"]     = context     unless context.nil?
+      profile["preferences"] = preferences unless preferences.nil?
+      @http.put("/api/v1/private/assistant/profile", profile)
+    end
+  end
+end

data/lib/melaya/auth.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Auth API — login, MFA, registration, password management, and session tokens.
+  #
+  # Most endpoints are public (no Bearer token needed for login/register).
+  # However, the SDK HttpClient always sends the mk_* API key which is fine —
+  # the server simply ignores it for public routes.
+  #
+  # Maps to /api/v1/private/auth/* and /api/v1/auth/*.
+  class AuthAPI
+    def initialize(http)
+      @http = http
+    end
+
+    # POST /api/v1/private/auth/login
+    # Password + username login; returns session JWT + optional MFA challenge token.
+    # @param username [String]
+    # @param password [String]
+    def login(username:, password:)
+      @http.post("/api/v1/private/auth/login",
+        "username" => username,
+        "password" => password)
+    end
+
+    # POST /api/v1/private/auth/mfa/verify
+    # Resolve MFA challenge after login.
+    # @param challenge_token [String]
+    # @param code [String] TOTP or recovery code
+    def verify_mfa(challenge_token:, code:)
+      @http.post("/api/v1/private/auth/mfa/verify",
+        "challengeToken" => challenge_token,
+        "code"           => code)
+    end
+
+    # POST /api/v1/private/auth/register
+    # Create a new user account; sends email verification.
+    def register(username:, email:, password:)
+      @http.post("/api/v1/private/auth/register",
+        "username" => username,
+        "email"    => email,
+        "password" => password)
+    end
+
+    # POST /api/v1/private/auth/verify-signup
+    # Confirm email address from signup link token.
+    # @param token [String]
+    def verify_signup(token:)
+      @http.post("/api/v1/private/auth/verify-signup", "token" => token)
+    end
+
+    # POST /api/v1/private/auth/resend-verification
+    # Re-send email verification message.
+    # @param email [String]
+    def resend_verification(email:)
+      @http.post("/api/v1/private/auth/resend-verification", "email" => email)
+    end
+
+    # GET /api/v1/private/auth/me
+    # Return current authenticated user profile.
+    def me
+      @http.get("/api/v1/private/auth/me")
+    end
+
+    # GET /api/v1/private/auth/check
+    # Lightweight session validity check; returns ok: true.
+    def check
+      @http.get("/api/v1/private/auth/check")
+    end
+
+    # POST /api/v1/private/auth/change-password
+    # Change password (current + new).
+    # @param current_password [String]
+    # @param new_password [String]
+    def change_password(current_password:, new_password:)
+      @http.post("/api/v1/private/auth/change-password",
+        "currentPassword" => current_password,
+        "newPassword"     => new_password)
+    end
+
+    # POST /api/v1/private/auth/forgot-password
+    # Initiate password reset flow; sends email with reset token.
+    # @param email [String]
+    def forgot_password(email:)
+      @http.post("/api/v1/private/auth/forgot-password", "email" => email)
+    end
+
+    # POST /api/v1/private/auth/reset-password
+    # Complete password reset using token from email.
+    # @param token [String]
+    # @param new_password [String]
+    def reset_password(token:, new_password:)
+      @http.post("/api/v1/private/auth/reset-password",
+        "token"       => token,
+        "newPassword" => new_password)
+    end
+
+    # POST /api/v1/private/auth/mobile-handoff
+    # Create a short-lived handoff token for mobile app deep-link auth.
+    def mobile_handoff
+      @http.post("/api/v1/private/auth/mobile-handoff")
+    end
+
+    # GET /api/v1/private/auth/permissions
+    # Return caller's permission flags (capabilities, tier, feature gates).
+    def permissions
+      @http.get("/api/v1/private/auth/permissions")
+    end
+
+    # POST /api/v1/private/auth/refresh
+    # Rotate session JWT (sliding expiry); returns new token.
+    def refresh
+      @http.post("/api/v1/private/auth/refresh")
+    end
+
+    # ── MFA ───────────────────────────────────────────────────────────────────
+
+    # GET /api/v1/private/mfa/status
+    # Return MFA enrollment status for the caller.
+    def mfa_status
+      @http.get("/api/v1/private/mfa/status")
+    end
+
+    # POST /api/v1/private/mfa/setup
+    # Initiate TOTP setup; returns QR/secret.
+    def mfa_setup
+      @http.post("/api/v1/private/mfa/setup")
+    end
+
+    # POST /api/v1/private/mfa/confirm
+    # Confirm TOTP setup with first valid code; activates MFA.
+    # @param code [String]
+    def mfa_confirm(code:)
+      @http.post("/api/v1/private/mfa/confirm", "code" => code)
+    end
+  end
+end