melaya 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47fefbce18553e5a38d414eb96ad35da805b1bb4d685e9fd809206b00d2dbe68
-  data.tar.gz: 822418410f53fc0cb03caf2fd06a8a122db8082e58ded4c68f6032dea5898965
+  metadata.gz: 523018c43fba39a422511cbfcc953f2a25f4dd0a2471c37a5b133544eee4ad0c
+  data.tar.gz: 777fe8a1777eceec586938329d36ea167c417f761282119cb3154519b60b87ca
 SHA512:
-  metadata.gz: 7680af7ede9b7cfa4e4fa2c6860c3e40260c488f2a3b6906930382b9a44ab36862ff8117ac6ce533bcac5fe5d7b8f12c4961257a61c149ebf6c07953da84e1e7
-  data.tar.gz: 6e929c21c54d44b99c0cfffa1d717ca85ca95bf0c95ecbc1d2e260e9343e8cc4383d47e38d7b9ffe965aa15798e7ee202ae2230f2fc4de75a21b15bdd2aa500e
+  metadata.gz: b32eaac6377a90e41146f33b5077eb5eb7369f277685fe2eaa5e97442a32f9393595fd5bb05cd3033376b3e5c9ff00ed93338fdeb73df5d97cf4e5f3ab03ff37
+  data.tar.gz: 7e0851368ebad8ee942bf1b14b7ad93a46b95da769cd75e68fd3201489b7ec53fa34f615262e15c64b1c61371548d87fb664ecf535f8fc6724c22f10f48a794d

data/README.md

@@ -8,7 +8,7 @@ Official SDK for the **[Melaya](https://melaya.org)** Agent Builder and flagship
 
 - 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).
+- Catalogs of **8,000+ scoped tools**, **100+ specialized subagents**, and **48 AI providers** (runtime catalog endpoints are the source of truth).
 - Pure Ruby WebSocket client (RFC 6455) — no external gem required for streaming.
 
 ## Install
@@ -146,6 +146,27 @@ outcome = melaya.agents.connector_tools.call_and_wait("gmail_send", args: { to:
 melaya.connector_tools.services
 ```
 
+### Quick start: diagnose an event trigger
+
+Read, diagnose and dry-run the event triggers that start your pipelines.
+Creating, editing and deleting a trigger stay in the Agent Builder and the MCP
+server. No method returns a signing secret. `test` and `poll_test` are dry
+runs: the action never executes.
+
+```ruby
+triggers = melaya.agents.triggers.list(project: "support")
+id = triggers[0]["id"]
+
+melaya.agents.triggers.stats(id, hours: 24)            # counts by verdict
+melaya.agents.triggers.events(trigger_id: id, verdicts: %w[rejected failed], limit: 50)
+melaya.agents.triggers.test(id, payload: { type: "refund.created" })  # dry run
+
+# Poll triggers
+melaya.agents.triggers.poll_status(id)
+dry = melaya.agents.triggers.poll_test(id)             # what it found and would publish
+puts dry["ok"] ? "#{dry["found"]} found, #{dry["wouldPublish"]} new" : dry["error"]
+```
+
 ## Trading quick start (preview)
 
 ```ruby
@@ -267,6 +288,7 @@ Public market-data and account/strategy reads work with the `mk_` key alone. **L
 | 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` |
+| Triggers | `triggers.list`, `get`, `deliveries`, `stats`, `pending_approvals`, `test`, `events`, `poll_status`, `poll_test`, `poll_now`, `poll_sync`, `presets`, `limits`, `sources` |
 | 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` |
@@ -286,7 +308,7 @@ Public market-data and account/strategy reads work with the `mk_` key alone. **L
 | 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).
+Every area is also reachable through the domain namespaces: `melaya.agents.*` (pipelines/runs, hitl, assistant, phone, evals, models, connector_tools, triggers) and `melaya.platform.*` (projects, credentials, connectors, billing, team, templates, overview, runner, auth, mfa, accounts, bugs, events).
 
 ### Trading (preview — not generally available)
 

data/lib/melaya/namespaces.rb

@@ -7,7 +7,7 @@ module Melaya
   # grouping the flat module accessors into logical planes:
   #
   #   melaya.trading  — market data, account, sim, strategies, backtest, stream, trade
-  #   melaya.agents   — pipelines/runs, hitl, assistant, phone, evals, models, connector_tools
+  #   melaya.agents   — pipelines/runs, hitl, assistant, phone, evals, models, connector_tools, triggers
   #   melaya.platform — projects, credentials, connectors, billing, team, templates,
   #                     overview (via pipelines), runner, auth, mfa (via auth),
   #                     accounts, bugs, events
@@ -63,6 +63,8 @@ module Melaya
   # - +connector_tools+ — Call already-connected connector tools directly
   #                  (Gmail, Slack, Stripe, ...): list, search, describe, test,
   #                  connect, call, call_status, call_and_wait.
+  # - +triggers+   — Event triggers: list, inspect, diagnose and dry-run
+  #                  triggers and poll triggers.
   AgentsNamespace = Struct.new(
     :pipelines,
     :hitl,
@@ -71,6 +73,7 @@ module Melaya
     :evals,
     :models,
     :connector_tools,
+    :triggers,
     keyword_init: true
   ) do
     # +runs+ is an ergonomic alias for +pipelines+ (agents call them "runs").

data/lib/melaya/triggers.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Melaya
+  # Triggers API: read, diagnose and dry-run the event triggers that start
+  # your pipelines.
+  #
+  # Maps to /api/v1/private/triggers/*.
+  #
+  # Read-only apart from the dry runs and poll controls. Creating, updating,
+  # deleting a trigger and rotating its signing secret stay in the Agent
+  # Builder and the MCP server, where push consent and autonomy grants are
+  # enforced. No method here returns a signing secret.
+  #
+  # +test+ and +poll_test+ are dry runs: the trigger's action never executes.
+  # +poll_now+ queues a real poll.
+  #
+  # @example
+  #   triggers = melaya.agents.triggers.list(project: "support")
+  #   stats    = melaya.agents.triggers.stats(triggers[0]["id"], hours: 24)
+  #
+  #   # What happened recently, including events that wrote no receipt.
+  #   live = melaya.agents.triggers.events(verdicts: %w[rejected failed], limit: 50)
+  #
+  #   # Dry run one event (the action never runs).
+  #   test = melaya.agents.triggers.test(triggers[0]["id"], payload: { type: "ping" })
+  #   # => { "accepted" => true, "eventId" => "test-..." }
+  #
+  #   # Also reachable via the flat alias:
+  #   melaya.triggers.limits
+  class TriggersAPI
+    BASE = "/api/v1/private/triggers"
+
+    def initialize(http)
+      @http = http
+    end
+
+    # ── Triggers ──────────────────────────────────────────────────────────────
+
+    # GET /triggers?project=&pipelineName=
+    # List your event triggers.
+    # @param project [String, nil] project name filter
+    # @param pipeline_name [String, nil] pipeline name filter
+    # @return [Array<Hash>] trigger records: id, publicId, name, kind, project,
+    #   pipelineName, enabled, pausedReason, signingScheme, sourceId, config,
+    #   rate caps, consecutiveFailures, lastEventAt, createdAt, updatedAt,
+    #   webhookUrl, projectAccess
+    def list(project: nil, pipeline_name: nil)
+      @http.get(BASE, compact("project" => project, "pipelineName" => pipeline_name))
+    end
+
+    # GET /triggers/:id
+    # One trigger with its config. Secrets are never included.
+    # @param id [String]
+    # @return [Hash]
+    def get(id)
+      @http.get("#{BASE}/#{enc(id)}")
+    end
+
+    # GET /triggers/:id/deliveries?limit=
+    # Recent deliveries (receipts) of a trigger: verdict, decision answers,
+    # action, run id and timings.
+    # @param id [String]
+    # @param limit [Integer, nil] 1-200, server default 50
+    # @return [Array<Hash>]
+    def deliveries(id, limit: nil)
+      @http.get("#{BASE}/#{enc(id)}/deliveries", compact("limit" => limit))
+    end
+
+    # GET /triggers/:id/stats?hours=
+    # Delivery counts by verdict over a window.
+    # @param id [String]
+    # @param hours [Integer, nil] 1-168, server default 24
+    # @return [Hash] { "hours" => Integer, "byVerdict" => { verdict => { "n", "p50", "p95" } },
+    #   "filtered" => Integer or nil, "sampled" => Boolean }
+    def stats(id, hours: nil)
+      @http.get("#{BASE}/#{enc(id)}/stats", compact("hours" => hours))
+    end
+
+    # GET /triggers/:id/approvals
+    # Approvals still waiting on this trigger's runs and tool calls. Read
+    # only: decide them in the Melaya app.
+    # @param id [String]
+    # @return [Array<Hash>]
+    def pending_approvals(id)
+      @http.get("#{BASE}/#{enc(id)}/approvals")
+    end
+
+    # POST /triggers/:id/test { payload }
+    # Dry run one event through the prefilter, the decide step and routing.
+    # The action never executes. The trigger's rate limits still apply, so a
+    # refused test comes back with "accepted" => false and a "reason"
+    # ("disabled", "rate_limited", ...). Follow the outcome with +events+
+    # for this trigger.
+    # @param id [String]
+    # @param payload [Object, nil] the event payload; omit for an empty object
+    # @return [Hash] { "accepted" => Boolean, "eventId" => String, "reason" => String (optional) }
+    def test(id, payload: nil)
+      @http.post("#{BASE}/#{enc(id)}/test", payload.nil? ? {} : { "payload" => payload })
+    end
+
+    # GET /triggers/events?triggerId=&since=&verdicts=&limit=
+    # Recent live trigger events, newest first (the last 500 events or 24
+    # hours), including the outcomes that write no receipt: filtered, shed,
+    # ingress rejections, feed refusals and push lifecycle notes. To follow
+    # new events, pass +since+ = the newest "at" already seen.
+    # @param trigger_id [String, nil] only this trigger's events
+    # @param since [Integer, nil] only events after this time, epoch milliseconds
+    # @param verdicts [Array<String>, String, nil] e.g. %w[rejected filtered failed]
+    # @param limit [Integer, nil] 1-200
+    # @return [Hash] { "events" => [Hash], "scanned" => Integer,
+    #   "retention" => { "maxEvents" => Integer, "ttlSec" => Integer } }
+    def events(trigger_id: nil, since: nil, verdicts: nil, limit: nil)
+      v = verdicts.is_a?(Array) ? verdicts.join(",") : verdicts
+      v = nil if v == ""
+      @http.get("#{BASE}/events",
+                compact("triggerId" => trigger_id, "since" => since, "verdicts" => v, "limit" => limit))
+    end
+
+    # ── Poll triggers ─────────────────────────────────────────────────────────
+
+    # GET /triggers/:triggerId/poll
+    # Runtime state of a poll trigger: synced, status, lastError,
+    # lastPolledAt, nextPollAt, armed, baselinePending, seenCount,
+    # itemsPublished, consecutiveErrors, requestedIntervalSec,
+    # effectiveIntervalSec, tierFloorSec.
+    # @param trigger_id [String]
+    # @return [Hash]
+    def poll_status(trigger_id)
+      @http.get("#{BASE}/#{enc(trigger_id)}/poll")
+    end
+
+    # POST /triggers/:triggerId/poll/test { dry: true }
+    # Dry poll: calls the poll tool now and returns what it found and would
+    # publish. Nothing is published. A poll that fails is returned as
+    # { "dry" => true, "ok" => false, "error" => code } instead of raised.
+    # Dry polls are throttled to one every few seconds (HTTP 429).
+    # @param trigger_id [String]
+    # @return [Hash] { "dry", "ok", "found", "baseline", "wouldPublish",
+    #   "items" => [{ "id", "preview" }], "samplePayload" } or { "dry", "ok" => false, "error" }
+    def poll_test(trigger_id)
+      @http.post("#{BASE}/#{enc(trigger_id)}/poll/test", "dry" => true)
+    rescue MelayaError => e
+      # A failed dry poll is a normal 200 result, not a request failure.
+      raise unless e.status.to_i < 400 && e.body.is_a?(Hash) && e.body.key?("dry")
+
+      e.body
+    end
+
+    # POST /triggers/:triggerId/poll/test { dry: false }
+    # Queue a real poll now. The trigger must be enabled ("trigger_disabled"
+    # otherwise). Follow the outcome with +poll_status+ and +events+.
+    # @param trigger_id [String]
+    # @return [Hash] { "dry" => false, "queued" => Boolean }
+    def poll_now(trigger_id)
+      @http.post("#{BASE}/#{enc(trigger_id)}/poll/test", "dry" => false)
+    end
+
+    # POST /triggers/:triggerId/poll/sync
+    # Re-create a poll trigger's runtime row from its saved config. Re-arms a
+    # trigger whose poller never started.
+    # @param trigger_id [String]
+    # @return [Hash] { "result" => Object }
+    def poll_sync(trigger_id)
+      @http.post("#{BASE}/#{enc(trigger_id)}/poll/sync", {})
+    end
+
+    # ── Account-wide ──────────────────────────────────────────────────────────
+
+    # GET /triggers/presets
+    # Trigger presets available to you, given your connected services and plan.
+    # @return [Hash] { "tier" => String, "tierFloorSec" => Integer, "presets" => [Hash], "beta" => Hash }
+    def presets
+      @http.get("#{BASE}/presets")
+    end
+
+    # GET /triggers/limits
+    # Plan caps and usage: triggers and sources used against the cap, events
+    # per minute, poll interval floor and approval TTL bounds.
+    # @return [Hash]
+    def limits
+      @http.get("#{BASE}/limits")
+    end
+
+    # GET /triggers/sources
+    # Your WebSocket and SSE stream sources.
+    # @return [Array<Hash>]
+    def sources
+      @http.get("#{BASE}/sources")
+    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/version.rb

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

data/lib/melaya.rb

@@ -24,6 +24,7 @@ require_relative "melaya/hitl"
 require_relative "melaya/credentials"
 require_relative "melaya/connectors"
 require_relative "melaya/connector_tools"
+require_relative "melaya/triggers"
 require_relative "melaya/phone"
 require_relative "melaya/team"
 require_relative "melaya/templates"
@@ -59,7 +60,7 @@ module Melaya
   # **Namespace groupings**:
   # - +trading+  — market, account, sim, strategies, backtest, stream, trade
   # - +agents+   — pipelines (also +.runs+), hitl, assistant, phone, evals, models,
-  #                connector_tools
+  #                connector_tools, triggers
   # - +platform+ — projects, credentials, connectors, billing, team, templates,
   #                overview, runner, auth (also +.mfa+), accounts, bugs, events
   #
@@ -132,6 +133,9 @@ module Melaya
     # — the same surface the MCP server and Assistant use. Not to be confused
     # with +connectors+ (credential storage).
     attr_reader :connector_tools
+    # Event triggers: list, inspect, diagnose and dry-run triggers and poll
+    # triggers. Create, update and delete stay in the Agent Builder and MCP.
+    attr_reader :triggers
     # Phone device control: pair, list, screen-tree, apps.
     attr_reader :phone
     # Project team management: members, roles, invite links.
@@ -163,7 +167,7 @@ module Melaya
 
     # Agent-plane namespace.
     # Groups: pipelines (alias: runs), hitl, assistant, phone, evals, models,
-    # connector_tools.
+    # connector_tools, triggers.
     #
     # @return [AgentsNamespace]
     # @example
@@ -174,6 +178,7 @@ module Melaya
     #   melaya.agents.evals.list_runs
     #   melaya.agents.models.list_models(provider: "anthropic")
     #   melaya.agents.connector_tools.services
+    #   melaya.agents.triggers.events(limit: 50)
     attr_reader :agents
 
     # Platform-plane namespace.
@@ -239,6 +244,7 @@ module Melaya
       @credentials = CredentialsAPI.new(http)
       @connectors  = ConnectorsAPI.new(http)
       @connector_tools = ConnectorToolsAPI.new(http)
+      @triggers    = TriggersAPI.new(http)
       @phone       = PhoneAPI.new(http)
       @team        = TeamAPI.new(http)
       @templates   = TemplatesAPI.new(http)
@@ -278,7 +284,8 @@ module Melaya
         # credentials#list_models is the canonical "models" surface; expose the
         # full CredentialsAPI object here so callers can do agents.models.list_models(...)
         models:    @credentials,
-        connector_tools: @connector_tools
+        connector_tools: @connector_tools,
+        triggers:  @triggers
       )
 
       # Platform namespace: events slot uses a lazy proxy so the Socket.IO

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: melaya
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Melaya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-27 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby SDK for Melaya Agent Builder and Mobile Device Control.
   Includes preview Melaya Trading namespaces that are not yet generally available.
@@ -48,6 +48,7 @@ files:
 - lib/melaya/team.rb
 - lib/melaya/templates.rb
 - lib/melaya/trade.rb
+- lib/melaya/triggers.rb
 - lib/melaya/version.rb
 - melaya.gemspec
 homepage: https://melaya.org