connectors 0.1.0

data/lib/connectors/action.rb

@@ -0,0 +1,90 @@
+module Connectors
+  # Declarative description of one thing a connector can DO with a credential
+  # — Slack "post message", Resend "send email", GitHub "create issue". The
+  # equivalent of an n8n node's `(resource, operation)` slot
+  # (packages/workflow/src/interfaces.ts NodeProperties) and Activepieces'
+  # `createAction(...)` declaration.
+  #
+  # The class is a value object — `ActionBuilder` materialises it from the
+  # DSL, `Connector.actions` stores them, `ActionRunner` invokes them.
+  # Frontend / agents read `to_manifest` to know what inputs the action
+  # accepts and what shape it returns.
+  #
+  #   action :send_email,
+  #          display_name: "Send Email",
+  #          description:  "Send a transactional email via Resend." do
+  #     field :from,        type: "string", required: true,
+  #           placeholder:  "Updates <updates@yourdomain.com>"
+  #     field :to,          type: "string", required: true,
+  #           type_options: { multiple_values: true }
+  #     field :subject,     type: "string", required: true
+  #     field :html,        type: "string", type_options: { editor: "html" }
+  #     field :text,        type: "string", type_options: { rows: 4 }
+  #
+  #     output do
+  #       field :id, type: "string", description: "Resend message id."
+  #     end
+  #
+  #     execute do |input|
+  #       send_email(**input.symbolize_keys)
+  #     end
+  #   end
+  class Action
+    # n8n's `NodePropertyTypes` (interfaces.ts:1561-1584) — a superset of what
+    # credentials accept. Action params can be richer than credential fields
+    # because they're the user's per-execution inputs, not the auth setup.
+    ALLOWED_TYPES = %w[
+      string number boolean
+      options multiOptions
+      json hidden notice
+      collection fixedCollection
+      dateTime color
+      resourceLocator resourceMapper
+      filter assignmentCollection
+    ].freeze
+
+    attr_reader :key, :display_name, :description, :params, :output, :execute_block,
+                :tags, :deprecated
+
+    def initialize(key:, display_name:, description: nil,
+                   params: [], output: [], execute_block: nil,
+                   tags: [], deprecated: false)
+      raise ArgumentError, "execute block is required for action #{key.inspect}" if execute_block.nil?
+
+      @key           = key.to_sym
+      @display_name  = display_name || key.to_s.tr("_", " ").capitalize
+      @description   = description
+      @params        = params
+      @output        = output
+      @execute_block = execute_block
+      @tags          = Array(tags).map(&:to_sym)
+      @deprecated    = deprecated == true
+    end
+
+    # Frontend / agent-facing shape. camelCase the keys that go into the
+    # property objects so they look identical to credential properties (the
+    # generic form renderer handles both with no special-casing). Output
+    # shape is the same — fields describing what the runner returns.
+    def to_manifest
+      {
+        name:         key.to_s,
+        display_name: display_name,
+        description:  description,
+        deprecated:   deprecated,
+        tags:         tags.map(&:to_s),
+        properties:   params.map(&:to_property),
+        output:       output.map(&:to_property)
+      }.compact
+    end
+
+    # Names of params marked `required: true`. Used by ActionRunner to
+    # short-circuit before the execute block runs.
+    def required_param_names
+      params.select(&:required?).map { |f| f.name.to_s }
+    end
+
+    def param_names
+      params.map { |f| f.name.to_s }
+    end
+  end
+end

data/lib/connectors/action_builder.rb

@@ -0,0 +1,125 @@
+module Connectors
+  # DSL surface for the `action` block on a Connector subclass. Collects
+  # `field`, optional `output`, and `execute` declarations into an Action
+  # value object.
+  #
+  # Reuses `CredentialSchema::Field` as the property struct because n8n's
+  # node-property shape and credential-property shape are identical (both
+  # `INodeProperties` at packages/workflow/src/interfaces.ts:1773-1812) —
+  # only the allowed `type` set differs (see `Action::ALLOWED_TYPES`).
+  class ActionBuilder
+    Field = CredentialSchema::Field
+
+    def self.build(key, display_name: nil, description: nil, tags: [], deprecated: false, &block)
+      builder = new(key, display_name: display_name, description: description,
+                         tags: tags, deprecated: deprecated)
+      builder.instance_eval(&block) if block
+      builder.to_action
+    end
+
+    def initialize(key, display_name:, description:, tags:, deprecated:)
+      @key           = key
+      @display_name  = display_name
+      @description   = description
+      @tags          = tags
+      @deprecated    = deprecated
+      @params        = []
+      @output        = []
+      @execute_block = nil
+    end
+
+    # Declare one input parameter. Mirrors `CredentialSchema#field` with the
+    # broader `Action::ALLOWED_TYPES` set — same kwargs, same semantics.
+    def field(name,
+              type:               "string",
+              display_name:       nil,
+              default:            nil,
+              placeholder:        nil,
+              description:        nil,
+              hint:               nil,
+              required:           false,
+              no_data_expression: false,
+              type_options:       nil,
+              display_options:    nil,
+              options:            nil)
+      raise ArgumentError, "unknown action field type #{type.inspect}; allowed: #{Action::ALLOWED_TYPES.inspect}" \
+        unless Action::ALLOWED_TYPES.include?(type.to_s)
+
+      @params << Field.new(
+        name:               name.to_sym,
+        display_name:       display_name,
+        type:               type.to_s,
+        default:            default,
+        placeholder:        placeholder,
+        description:        description,
+        hint:               hint,
+        required:           required == true,
+        no_data_expression: no_data_expression == true,
+        type_options:       type_options,
+        display_options:    display_options,
+        options:            options
+      )
+    end
+
+    # Declare the shape of the value the action returns. Optional but
+    # encouraged — agents and downstream nodes use it to know what fields
+    # they can reference (Activepieces calls this `returns:`). The same
+    # `field` DSL is used inside the block.
+    def output(&block)
+      raise ArgumentError, "output requires a block" if block.nil?
+      collector = OutputCollector.new
+      collector.instance_eval(&block)
+      @output = collector.fields
+    end
+
+    # Capture the execute block. Invoked by `ActionRunner` in the connector
+    # instance's context, so `self.client`, `self.send_email`, etc. are all
+    # accessible. Receives one positional Hash of params.
+    def execute(&block)
+      raise ArgumentError, "execute requires a block" if block.nil?
+      @execute_block = block
+    end
+
+    def to_action
+      Action.new(
+        key:           @key,
+        display_name:  @display_name,
+        description:   @description,
+        params:        @params,
+        output:        @output,
+        execute_block: @execute_block,
+        tags:          @tags,
+        deprecated:    @deprecated
+      )
+    end
+
+    # Tiny sibling builder so `output do field ... end` can reuse the same
+    # `field` semantics without picking up the outer builder's @params slot.
+    class OutputCollector
+      attr_reader :fields
+
+      def initialize
+        @fields = []
+      end
+
+      def field(name,
+                type:         "string",
+                display_name: nil,
+                description:  nil,
+                hint:         nil,
+                type_options: nil,
+                options:      nil)
+        @fields << CredentialSchema::Field.new(
+          name:         name.to_sym,
+          display_name: display_name,
+          type:         type.to_s,
+          description:  description,
+          hint:         hint,
+          required:     false,
+          type_options: type_options,
+          options:      options
+        )
+      end
+    end
+  end
+end

data/lib/connectors/action_runner.rb

@@ -0,0 +1,99 @@
+module Connectors
+  # Validates an Action's input params and invokes its execute block in the
+  # connector instance's context. Returns a normalized response envelope —
+  # both the controller and the (eventual) workflow executor consume the
+  # same shape.
+  #
+  #   result = ActionRunner.call(grant, :send_email, { "from" => "x", "to" => "y", ... })
+  #   # => { status: "ok",    action: "send_email", data: { "id" => "abc-123" } }
+  #   # or
+  #   # => { status: "error", action: "send_email",
+  #   #      error: { type: "api_error", message: "...", status: 422 } }
+  #
+  # The runner does not catch arbitrary StandardError — only Connectors::
+  # errors. Anything else propagates so the caller can render a 500. This
+  # mirrors how the workflow executor expects "unexpected" failures to be
+  # visible in logs rather than silently absorbed.
+  class ActionRunner
+    OK    = "ok".freeze
+    ERROR = "error".freeze
+
+    def self.call(grant, action_name, input)
+      new(grant, action_name, input).call
+    end
+
+    def initialize(grant, action_name, input)
+      @grant       = grant
+      @action_name = action_name
+      @input       = (input || {}).transform_keys(&:to_s)
+    end
+
+    def call
+      action = @grant.connector.class.action_lookup(@action_name)
+      @grant.ensure_not_revoked!
+      validate!(action)
+
+      result = @grant.connector.instance_exec(coerced_input(action), &action.execute_block)
+
+      { status: OK, action: action.key.to_s, data: result }
+    rescue Connectors::InvalidActionParams => e
+      error_envelope(action&.key,
+                     type: "invalid_params", message: e.message,
+                     details: { missing: e.missing, unknown: e.unknown })
+    rescue Connectors::AuthenticationFailed => e
+      error_envelope(action&.key, type: "authentication_failed", message: e.message,
+                     details: { status: safe_status(e) })
+    rescue Connectors::Forbidden => e
+      error_envelope(action&.key, type: "forbidden", message: e.message, details: { status: safe_status(e) })
+    rescue Connectors::RateLimited => e
+      error_envelope(action&.key, type: "rate_limited", message: e.message,
+                     details: { status: safe_status(e), retry_after: e.retry_after })
+    rescue Connectors::ApiError => e
+      error_envelope(action&.key, type: "api_error", message: e.message,
+                     details: { status: safe_status(e), body: e.body })
+    rescue Connectors::UnknownAction => e
+      # `action` is nil here — re-raise so the controller renders a 404
+      # rather than a 200 with an error body (mirrors UnknownConnector).
+      raise
+    end
+
+    private
+
+    def validate!(action)
+      provided = @input.keys
+      missing  = action.required_param_names.reject { |k| @input.key?(k) && !blank?(@input[k]) }
+      raise Connectors::InvalidActionParams.new(missing: missing) if missing.any?
+      # Note: we intentionally don't reject `unknown:` keys. n8n nodes
+      # frequently pass `additionalFields` collections that pack many
+      # optional values under one key; the connector's execute block
+      # decides which subset to honor. Strict-mode rejection can come
+      # later as an opt-in DSL flag.
+      _ = provided
+    end
+
+    # Whitelist incoming keys to the action's declared param names so the
+    # execute block doesn't see surprise data from a malformed caller. Keys
+    # arrive as strings (JSON), which is what every connector method in the
+    # codebase keyword-splats from — execute blocks call `**input.symbolize_keys`.
+    def coerced_input(action)
+      allowed = action.param_names.to_set
+      @input.slice(*allowed)
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def safe_status(err)
+      err.respond_to?(:status) ? err.status : nil
+    end
+
+    def error_envelope(action_key, type:, message:, details: {})
+      {
+        status: ERROR,
+        action: action_key.to_s,
+        error:  { type: type, message: message }.merge(details.compact)
+      }
+    end
+  end
+end

data/lib/connectors/auth/scheme/api_key.rb

@@ -0,0 +1,51 @@
+require "cgi"
+
+module Connectors
+  module Auth
+    class Scheme
+      # Attaches a static API key from grant.credentials["api_key"]. The
+      # location (header vs query), parameter name, and optional prefix are
+      # declared by the connector class via the `api_key_in` DSL:
+      #
+      #   class GithubConnector < Connectors::Connector
+      #     connector  key: :github, auth: :api_key, base_url: "https://api.github.com"
+      #     api_key_in :header, name: "Authorization", prefix: "token "
+      #   end
+      #
+      # Default placement is `Authorization: Bearer <key>`.
+      class ApiKey < Scheme
+        register_as :api_key
+
+        DEFAULT_OPTIONS = { location: :header, name: "Authorization", prefix: "Bearer " }.freeze
+
+        def on_request(env)
+          key = @grant.credentials_hash["api_key"]
+          if key.nil? || key.to_s.empty?
+            raise Connectors::AuthenticationFailed.new("grant #{@grant.id} has no api_key")
+          end
+
+          opts  = connector_options
+          value = "#{opts[:prefix]}#{key}"
+
+          case opts[:location]
+          when :header
+            env.request_headers[opts[:name]] = value
+          when :query
+            existing = env.url.query
+            pair     = "#{opts[:name]}=#{CGI.escape(value)}"
+            env.url.query = [ existing, pair ].compact.reject(&:empty?).join("&")
+          else
+            raise Connectors::Error.new("ApiKey scheme: unknown location #{opts[:location].inspect}")
+          end
+        end
+
+        private
+
+        def connector_options
+          klass = @grant.connector.class
+          (klass.respond_to?(:api_key_options) && klass.api_key_options) || DEFAULT_OPTIONS
+        end
+      end
+    end
+  end
+end

data/lib/connectors/auth/scheme/oauth2.rb

@@ -0,0 +1,23 @@
+module Connectors
+  module Auth
+    class Scheme
+      # Attaches an OAuth2 access token as a Bearer Authorization header. The
+      # token is read from grant.credentials["access_token"]. Token refresh is
+      # handled separately by the AutoRefresh middleware + the connector's
+      # #refresh! method.
+      class OAuth2 < Scheme
+        register_as :oauth2
+
+        def on_request(env)
+          token = @grant.credentials_hash["access_token"]
+          if token.nil? || token.to_s.empty?
+            raise Connectors::AuthenticationFailed.new(
+              "grant #{@grant.id} has no access_token"
+            )
+          end
+          env.request_headers["Authorization"] = "Bearer #{token}"
+        end
+      end
+    end
+  end
+end

data/lib/connectors/auth/scheme.rb

@@ -0,0 +1,35 @@
+require "faraday"
+
+module Connectors
+  module Auth
+    # Abstract base class for auth schemes (OAuth2, ApiKey, HMAC, etc.). A
+    # scheme is just a Faraday middleware that mutates the outgoing request
+    # env with whatever the third-party service expects (Bearer header, signed
+    # query, etc.).
+    #
+    # Subclasses register themselves with a symbolic key via `register_as`,
+    # which is what the connector DSL `auth: :oauth2` resolves against.
+    class Scheme < Faraday::Middleware
+      class << self
+        def register_as(name)
+          Scheme.registry[name.to_sym] = self
+        end
+
+        def lookup(name)
+          registry.fetch(name.to_sym) { raise UnknownAuthScheme.new(name, known: registry.keys) }
+        end
+
+        def registry
+          @registry ||= {}
+        end
+      end
+
+      def initialize(app, grant:)
+        super(app)
+        @grant = grant
+      end
+
+      # Subclasses override on_request(env) to attach credentials.
+    end
+  end
+end

data/lib/connectors/auth.rb

@@ -0,0 +1,4 @@
+module Connectors
+  module Auth
+  end
+end

data/lib/connectors/auth_injection.rb

@@ -0,0 +1,65 @@
+module Connectors
+  # Resolves n8n-style `={{$credentials.x}}` templates inside an
+  # `IAuthenticateGeneric` properties block (n8n source:
+  # packages/workflow/src/interfaces.ts:269-288, 197-208).
+  #
+  # Scope on purpose: this is NOT a general-purpose expression engine. It
+  # only understands `$credentials.<field>` lookups (with optional bracket
+  # access). Anything richer belongs in the automations expression engine,
+  # which the connectors engine must remain independent of.
+  #
+  # A string that starts with `=` is a template — its `{{ ... }}` segments
+  # are evaluated. Strings without a leading `=` are passed through as
+  # literals (matches n8n's `={{expression}}` convention).
+  module AuthInjection
+    module_function
+
+    # Walk a properties Hash (`{ headers: {...}, qs: {...}, body: {...},
+    # auth: { username:, password: } }`), resolving every leaf string against
+    # `credentials`. Non-string leaves pass through.
+    def resolve(properties, credentials)
+      walk(properties, credentials || {})
+    end
+
+    def walk(value, credentials)
+      case value
+      when Hash
+        # Both keys AND values can be templates. n8n's HttpHeaderAuth uses
+        # `{ '={{$credentials.name}}': '={{$credentials.value}}' }` — the
+        # header *name* is user-supplied (see
+        # packages/nodes-base/credentials/HttpHeaderAuth.credentials.ts:38-45).
+        value.each_with_object({}) do |(k, v), out|
+          resolved_key = k.is_a?(String) ? resolve_string(k, credentials) : k
+          out[resolved_key] = walk(v, credentials)
+        end
+      when Array  then value.map { |v| walk(v, credentials) }
+      when String then resolve_string(value, credentials)
+      else value
+      end
+    end
+
+    EXPR = /\{\{\s*(.+?)\s*\}\}/.freeze
+
+    def resolve_string(str, credentials)
+      return str unless str.start_with?("=")
+      str[1..].gsub(EXPR) { lookup(Regexp.last_match(1), credentials) }
+    end
+
+    # Supports `$credentials.field`, `$credentials["field"]`, `$credentials['field']`.
+    # Missing keys resolve to "" (n8n behavior — keeps templates from raising
+    # mid-request when the field is optional).
+    def lookup(expr, credentials)
+      expr = expr.to_s.strip
+      if (m = expr.match(/\A\$credentials\.([A-Za-z_][A-Za-z0-9_]*)\z/))
+        credentials[m[1]].to_s
+      elsif (m = expr.match(/\A\$credentials\[(["'])(.+?)\1\]\z/))
+        credentials[m[2]].to_s
+      else
+        # Unknown expression syntax — pass through verbatim wrapped, so a
+        # user typo is visible in the outgoing request rather than silently
+        # erasing the header.
+        "{{#{expr}}}"
+      end
+    end
+  end
+end

data/lib/connectors/client_builder.rb

@@ -0,0 +1,87 @@
+require "faraday"
+require "faraday/retry"
+
+module Connectors
+  # Assembles the Faraday client used by a connector. Middleware order matters:
+  # outermost (declared first) wraps everything below. On the response side,
+  # outer middleware runs LAST, so anything that needs the parsed JSON body
+  # (ErrorNormalization, AutoRefresh's rescue path) must sit OUTER to the JSON
+  # response parser.
+  #
+  # Stack (outer → inner):
+  #   1. JSON request encoder                      — body marshaling
+  #   2. RateLimit                                  — per-grant quota
+  #   3. AutoRefresh                                — rescues 401 -> refresh -> retry
+  #   4. ErrorNormalization                         — raises after retry exhaustion
+  #   5. Retry / JSON response parser               — inspect parsed responses
+  #   6. GrantStatus                               — reject revoked grants on each attempt
+  #   7. PreAuthentication (Phase 3)                — proactive token refresh
+  #   8. Auth injection — declarative or imperative (one or the other)
+  #   9. Adapter                                    — sends the HTTP request
+  class ClientBuilder
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_TIMEOUT      = 30
+
+    # `authenticate_config` is the connector class's declarative
+    # `authenticate type: :generic, properties: {...}` block (Phase 1). When
+    # present, AuthenticateGeneric middleware applies it. When absent, fall
+    # back to the imperative `auth_scheme` middleware (legacy path —
+    # `Auth::Scheme::ApiKey` / `Auth::Scheme::OAuth2`).
+    #
+    # `pre_auth_block` is the connector's `pre_authentication` block (Phase 3).
+    # When present, PreAuthentication middleware runs it before each request
+    # whose grant credentials look stale (expires_at missing or in the past).
+    def initialize(base_url:, grant:, auth_scheme:, authenticate_config: nil, pre_auth_block: nil,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT, timeout: DEFAULT_TIMEOUT)
+      @base_url            = base_url
+      @grant               = grant
+      @auth_scheme         = auth_scheme
+      @authenticate_config = authenticate_config
+      @pre_auth_block      = pre_auth_block
+      @open_timeout        = open_timeout
+      @timeout             = timeout
+    end
+
+    def build
+      grant               = @grant
+      auth_scheme         = @auth_scheme
+      authenticate_config = @authenticate_config
+      pre_auth_block      = @pre_auth_block
+      open_timeout        = @open_timeout
+      timeout             = @timeout
+
+      Faraday.new(url: @base_url) do |f|
+        f.options.open_timeout = open_timeout
+        f.options.timeout      = timeout
+
+        f.request :json
+        f.use Middleware::RateLimit,   grant: grant
+        f.use Middleware::AutoRefresh, grant: grant
+        f.use Middleware::ErrorNormalization,
+              token_expired_status: grant.connector.class.oauth2_config&.fetch(:token_expired_status, 401) || 401
+        f.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                          retry_statuses: [ 502, 503, 504 ],
+                          methods: [ :get, :head, :options, :put, :delete ]
+        f.response :json, content_type: /\bjson\z/
+        f.use Middleware::GrantStatus, grant: grant
+
+        # PreAuthentication MUST sit before AuthenticateGeneric so the fresh
+        # credentials it writes to the grant are visible to the template
+        # resolver on the same request.
+        if pre_auth_block
+          f.use Middleware::PreAuthentication, grant: grant, pre_auth_block: pre_auth_block
+        end
+
+        if authenticate_config
+          f.use Middleware::AuthenticateGeneric,
+                grant:               grant,
+                authenticate_config: authenticate_config
+        else
+          f.use auth_scheme, grant: grant
+        end
+
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end