connectors 0.1.0 → 0.1.1

data/app/connectors/resend/connector.rb

@@ -35,10 +35,8 @@ module Resend
             description:  "Generate at https://resend.com/api-keys."
     end
 
-    # Phase 1 — declarative auth injection (mirrors n8n's HttpBearerAuth at
-    # packages/nodes-base/credentials/HttpBearerAuth.credentials.ts:38-45).
-    # The `={{...}}` template is resolved per-request from the Grant's
-    # credentials hash by `Middleware::AuthenticateGeneric`.
+    # AuthenticateGeneric resolves this template from the grant's
+    # credentials for each outgoing request.
     authenticate type: :generic, properties: {
       headers: { "Authorization" => "=Bearer {{$credentials.api_key}}" }
     }

data/app/controllers/connectors/actions_controller.rb

@@ -9,12 +9,6 @@ module Connectors
   # the action's param schema, then dispatches through `ActionRunner`. The
   # response envelope is always `{ status: "ok"|"error", action:, ... }` so
   # frontends and workflow executors consume the same shape.
-  #
-  # n8n parity: this is the moral equivalent of the executor's per-node
-  # `execute()` step (packages/core/src/node-execute-functions.ts) reachable
-  # over HTTP. The workflow engine in `automations/` will eventually call
-  # `ActionRunner.call(grant, action, input)` directly without going
-  # through HTTP — same path, no controller in the loop.
   class ActionsController < ApplicationController
     # Order matters: Rails `rescue_from` iterates in REVERSE declaration
     # order, so the more-specific subclasses must be declared AFTER

data/app/controllers/connectors/credentials_controller.rb

@@ -1,12 +1,6 @@
 module Connectors
-  # n8n-shaped credential CRUD. Underneath, a "credential" is a Grant — but
-  # this controller exposes it under the vocabulary the frontend uses
-  # (matches packages/cli/src/credentials/credentials.controller.ts:67-411).
-  #
-  # The paste-the-key flow lives here: `POST /credentials` with `{type,
-  # name, data}` creates a Grant directly without the OAuth dance.
-  # OAuth-issued grants continue to flow through OAuthController#callback
-  # and show up in this list automatically.
+  # Credential CRUD backed by Grant records. POST accepts `{type, name, data}`
+  # for API-key connections. OAuth-created grants appear in the same list.
   class CredentialsController < ApplicationController
     # Order matters: Rails `rescue_from` iterates in REVERSE declaration
     # order, so the more-specific subclasses must be declared AFTER
@@ -24,8 +18,7 @@ module Connectors
     #
     # Returns the union of: credentials this owner owns + credentials shared
     # with any of the requester's principals (User, Team, Project — whatever
-    # the host's `principal_resolver` returns). n8n parity:
-    # enterprise/credentials.controller.ee.ts.
+    # the host's `principal_resolver` returns).
     def index
       grants = visible_grants
       grants = grants.for_connector(params[:type]) if params[:type].present?
@@ -53,8 +46,7 @@ module Connectors
     # When `is_managed: true` is passed (typically alongside `external_ref:
     # "vault/path/foo"`), the DB only stores the reference + non-sensitive
     # field defaults; the actual credential values come from the host's
-    # `secrets_resolver` at request time. n8n parity: external-secrets EE
-    # module (external-secrets.controller.ee.ts).
+    # `secrets_resolver` at request time.
     def create
       owner = current_owner!
       type  = params.fetch(:type)
@@ -81,9 +73,7 @@ module Connectors
     end
 
     # GET /connectors/credentials/new?type=resend
-    # Server-generated unique default name ("Resend account 3"). n8n parity:
-    # `credentials.controller.ts:100-111`. The frontend pre-fills the name
-    # field with the response so the user can rename or accept the default.
+    # Returns a unique suggested name, such as "Resend account 3".
     def new
       current_owner!
       type = params.fetch(:type)
@@ -156,8 +146,7 @@ module Connectors
     end
 
     # PUT /connectors/credentials/:id/transfer
-    # Body: { owner_id: <uuid> } — moves ownership to a different owner.
-    # n8n parity: enterprise/credentials.controller.ee.ts transfer endpoint.
+    # Body: { owner_id: <uuid> } — transfers ownership to another host owner.
     def transfer
       grant         = find_visible_grant!(params[:id], min_role: :owner)
       new_owner_klass = Connectors.configuration.owner_class_name.constantize
@@ -203,7 +192,7 @@ module Connectors
     def serialize(grant, include_data: false)
       h = {
         id:                  grant.id,
-        type:                grant.connector_key,                       # n8n name
+        type:                grant.connector_key,
         connector_key:       grant.connector_key,                       # @deprecated alias
         name:                grant.display_name || "#{grant.connector_key} ##{grant.id}",
         external_account_id: grant.external_account_id,
@@ -213,13 +202,11 @@ module Connectors
         created_at:          grant.created_at,
         updated_at:          grant.updated_at,
         scopes:              extract_scopes(grant),
-        # Phase 10 — external secrets manager. `is_managed: true` means the
-        # actual credential values are vault-sourced; `external_ref` is the
-        # opaque key the host's `secrets_resolver` uses to look them up.
+        # `is_managed` selects vault-sourced credentials. `external_ref` is
+        # the opaque lookup key passed to the host secrets resolver.
         is_managed:          grant.is_managed,
         external_ref:        grant.external_ref,
-        # n8n's `__overwrittenProperties` (interfaces.ts:382) but per-grant
-        # so the editor can show "this field comes from Vault: <api_key>".
+        # Field names sourced from the vault, for display as managed inputs.
         __overwritten_properties: grant.is_managed ? Connectors.configuration.managed_fields_for(grant.connector_key) : []
       }
       if include_data

data/app/controllers/connectors/grants_controller.rb

@@ -21,9 +21,8 @@ module Connectors
     end
 
     # POST /connectors/grants/:id/test
-    # Runs the connector's declared `test_request` against the live
-    # provider using THIS grant's credentials. Returns `{status, message}`
-    # — n8n parity (packages/cli/src/credentials/credentials.controller.ts:141-152).
+    # Runs the declared provider test using this grant's credentials
+    # and returns `{status, message}`.
     def test
       owner = current_owner!
       grant = Grant.where(owner: owner).find(params[:id])
@@ -33,13 +32,10 @@ module Connectors
     end
 
     # POST /connectors/grants/:id/webhook_subscribe
-    # Runs the connector's `webhook_methods` create flow (skipping when
-    # check_exists already returns true). Manual entry point for Phase 6 —
-    # the workflow activation manager will call into this same lifecycle
-    # primitive (`Connectors::WebhookLifecycle.subscribe`) once it ships.
+    # Runs WebhookLifecycle.subscribe, skipping creation when check_exists succeeds.
     #
     # Params:
-    #   webhook_name=:default — group name (multi-webhook providers)
+    #   webhook_name=:default — subscription group
     #   hook_url=<override>   — defaults to the per-grant or app-level URL
     def webhook_subscribe
       owner = current_owner!
@@ -62,9 +58,8 @@ module Connectors
     end
 
     # POST /connectors/grants/:id/poll
-    # Runs the connector's `polling` block once. Manual harness for Phase 8 —
-    # the workflow-side scheduler will call into `Connectors::PollRunner.run`
-    # directly once it ships.
+    # Runs the connector's polling block once through PollRunner.
+    # The host controls scheduling.
     def poll
       owner  = current_owner!
       grant  = Grant.where(owner: owner).find(params[:id])

data/app/controllers/connectors/types_controller.rb

@@ -1,13 +1,7 @@
 module Connectors
-  # Catalog of every connector class registered in the engine. Read by the
-  # frontend at startup to render the "Add credential" form, the connect-OAuth
-  # popup, the credential picker on nodes — purely by reading this metadata.
-  # No per-connector frontend logic.
-  #
-  # Response shape mirrors n8n's `ICredentialType` description (n8n source:
-  # packages/workflow/src/interfaces.ts:356-382) so a single frontend renderer
-  # handles every connector. Returns only static metadata — never any secrets
-  # or per-user state.
+  # Static catalog of registered connectors. Clients use its metadata to
+  # render credential forms, authorization links and action inputs.
+  # The catalog contains no secrets or per-user state.
   class TypesController < ApplicationController
     # GET /connectors/types
     def index
@@ -42,10 +36,8 @@ module Connectors
       schema = klass.credential_schema
 
       {
-        # `name` is the n8n vocabulary for the machine identifier; `display_name`
-        # is the picker label. We keep `key`/`label` as aliases for back-compat
-        # with the existing /grants response — frontend should prefer the n8n
-        # names going forward.
+        # `name` identifies the connector; `display_name` is its UI label.
+        # `key` and `label` remain aliases for existing consumers.
         name:              key.to_s,
         display_name:      klass.display_name || key.to_s.humanize,
         key:               key.to_s,                                       # @deprecated — use `name`
@@ -65,44 +57,29 @@ module Connectors
         # or install an app first (e.g. Resend).
         instructions:      klass.instructions,
 
-        # n8n inheritance chain. Empty array when the credential type stands
-        # alone (e.g., API-key connectors). Frontend can fetch the parent's
-        # schema via `/connectors/types/:parent` OR rely on the resolved
-        # `properties` array below which already merges parent + own.
+        # Credential inheritance chain. The properties below already merge
+        # inherited and local fields, with local definitions taking precedence.
         extends:          schema ? schema.extends.map(&:to_s) : [],
         properties:       schema ? schema.resolved_fields.map(&:to_property) : [],
 
-        # Declarative auth injection — mirrors n8n's `IAuthenticateGeneric`
-        # at packages/workflow/src/interfaces.ts:278-288. Reads the resolved
-        # config (connector-level override OR inherited from the credential
-        # type via `extends`). nil when the connector still uses the
-        # imperative `api_key_in` shim AND no parent declared one.
+        # Resolved auth injection: connector override, then inherited schema.
+        # Nil when neither declares an authenticate block.
         authenticate:     klass.resolved_authenticate_config,
-        # n8n's `genericAuth: boolean` (`interfaces.ts:379`). True when the
-        # connector itself flips `generic_auth!` OR when it extends a schema
-        # that already does (HttpBearerAuth etc.).
+        # True when the connector or an inherited schema enables generic_auth.
         generic_auth:     klass.generic_auth?,
 
-        # n8n's `supportedNodes: string[]` (`interfaces.ts:381`). Empty array
-        # means "no restriction" — same default as n8n. The frontend uses
-        # this to filter the credential picker per node type.
+        # Allowed node types. An empty list imposes no node-type restriction.
         supported_nodes:  klass.supported_nodes.map(&:to_s),
 
-        # n8n's `httpRequestNode: ICredentialHttpRequestNode` (interfaces.ts:380,
-        # union shape at :350-354). Tells the generic HTTP-Request node's
-        # credential picker how to label + link this credential. nil when the
-        # connector hasn't declared it.
+        # Optional label, documentation link and base URL for an HTTP-request
+        # credential picker.
         http_request_node: klass.http_request_node,
 
-        # n8n's `__overwrittenProperties: string[]` (`interfaces.ts:382`;
-        # populated at `frontend.service.ts:681-705`). Field names whose
-        # values are sourced from the external secrets manager — the editor
-        # renders them locked / hidden. Empty array when no vault is
-        # configured for this connector type.
+        # Vault-sourced field names for the editor to display as managed.
+        # Empty when the host has not configured managed fields for this type.
         __overwritten_properties: Connectors.configuration.managed_fields_for(key),
 
-        # n8n's `__skipManagedCreation` (frontend.service.ts:707-711). When
-        # true the editor hides the "Use external secret" toggle.
+        # When true, clients should hide managed-credential creation.
         __skip_managed_creation: klass.skip_managed_creation?,
 
         # Action manifest — what this connector can DO with a credential.
@@ -113,12 +90,8 @@ module Connectors
         # connector hasn't declared any actions yet.
         actions: klass.actions.map(&:to_manifest),
 
-        # Connector capabilities — orthogonal to credentials. Lives in its own
-        # block so frontend code that only cares about credential rendering
-        # can ignore it. For OAuth connectors, `redirect_uri` is the URL the
-        # admin must paste into the provider's app console (computed from the
-        # host's base URL — n8n does the same server-side at
-        # packages/cli/src/oauth/oauth.service.ts:528,690).
+        # Connector capabilities, separate from credential form metadata.
+        # OAuth redirect_uri is the callback URL to register with the provider.
         connector: {
           base_url:      klass.base_url,
           webhook_style: klass.webhook_style.to_s,

data/app/controllers/connectors/webhooks_controller.rb

@@ -83,10 +83,8 @@ module Connectors
         request.headers["Signature"]
     end
 
-    # Capture every HTTP_* header on the inbound request, normalized to
-    # lowercase + dashed keys (`http_x_hub_signature` → `x-hub-signature`),
-    # so the n8n-style `ctx.headers["stripe-signature"]` access works
-    # without callers having to know about Rack's mangling.
+    # Normalize inbound HTTP_* headers to lowercase, dashed names
+    # so handlers can use `ctx.headers["stripe-signature"]`.
     def inbound_headers
       request.headers.env.each_with_object({}) do |(k, v), out|
         next unless k.start_with?("HTTP_")

data/app/jobs/connectors/deliver_webhook_job.rb

@@ -8,10 +8,8 @@ module Connectors
       event = WebhookEvent.find(event_id)
       return if event.processed? || event.ignored?
 
-      # Phase 7: always hand the connector a `WebhookContext` (n8n parity
-      # with `IWebhookFunctions`). The context still exposes `.event` /
-      # `.payload_hash` so handlers written against the old `event` arg
-      # keep working without changes — the new accessors are additive.
+      # Pass request data through WebhookContext. Its event and payload_hash
+      # accessors also support handlers that consume the persisted event.
       event.grant.connector.handle_webhook(Connectors::WebhookContext.new(event))
       event.update!(status: :processed, processed_at: Time.current, error_message: nil)
 

data/app/models/connectors/credential_share.rb

@@ -1,14 +1,7 @@
 module Connectors
-  # One sharing entry per (grant, principal) pair. The engine intentionally
-  # doesn't know what a principal is — `principal_type` / `principal_id`
-  # are opaque tuples supplied by the host's
-  # `Connectors.configuration.principal_resolver` block.
-  #
-  # `role` mirrors n8n's enterprise model: viewer = read-only, editor =
-  # update + use, owner = full control (delete + share + transfer). Only
-  # one `:owner` per grant — enforced by the unique index on
-  # `(grant_id, principal_type, principal_id)` plus a custom uniqueness
-  # validation per role.
+  # One sharing entry per (grant, principal) pair. Principal type and ID
+  # are supplied by the host principal_resolver. Roles are viewer, editor
+  # and owner; GrantPolicy defines their permitted operations.
   class CredentialShare < ApplicationRecord
     self.table_name = "connectors_credential_shares"
 

data/app/models/connectors/grant.rb

@@ -73,10 +73,8 @@ module Connectors
       credentials || {}
     end
 
-    # Mirrors n8n's `getWorkflowStaticData('node')` — a small scratch hash
-    # the connector mutates between webhook lifecycle calls (or polling
-    # cursors). Save with `save!` after mutation, or use
-    # `update_static_data!(group, &block)` for the atomic path.
+    # Scratch storage for webhook subscriptions and polling cursors.
+    # Save after mutation or use update_static_data! for an atomic update.
     def static_data_hash
       static_data || {}
     end

data/config/routes.rb

@@ -5,9 +5,7 @@ Connectors::Engine.routes.draw do
   post "/credentials/:id/mcp/authorize", to: "mcp#authorize"
   get  "/mcp/oauth/callback", to: "mcp#callback"
   post "/mcp/oauth/callback", to: "mcp#callback"
-  # Catalog + connected-account introspection. Declared first so /grants and
-  # /types aren't interpreted as a :connector_key.
-  # n8n-shape credential CRUD (the canonical endpoints — frontend uses these).
+  # Catalog and credential routes precede the dynamic :connector_key routes.
   get    "/credentials",                    to: "credentials#index",        as: :credentials
   get    "/credentials/for-workflow",       to: "credentials#for_workflow", as: :credentials_for_workflow
   post   "/credentials/test",               to: "credentials#test_unsaved", as: :test_unsaved_credential
@@ -26,7 +24,7 @@ Connectors::Engine.routes.draw do
   post   "/credentials/:id/actions/:name",  to: "actions#create",           as: :invoke_credential_action,
                                             constraints: { name: /[^\/]+/ }
 
-  # Phase 9 — credential sharing / scoping
+  # Credential sharing and ownership transfer.
   put    "/credentials/:id/share",          to: "credentials#share",        as: :share_credential
   delete "/credentials/:id/share",          to: "credentials#unshare"
   put    "/credentials/:id/transfer",       to: "credentials#transfer",     as: :transfer_credential
@@ -40,25 +38,20 @@ Connectors::Engine.routes.draw do
   get  "/types",                            to: "types#index",      as: :types
   get  "/types/:name",                      to: "types#show",       as: :type, constraints: { name: /[^\/]+/ }
 
-  # Split frontend/backend OAuth completion (Activepieces-style). The
-  # frontend's `/oauth/callback` page POSTs `{code, state}` here after the
-  # provider redirects to it.
+  # Separate frontend callbacks POST `{code, state}` here after consent.
   post "/oauth/exchange",                   to: "oauth#exchange",       as: :oauth_exchange
 
   get  "/:connector_key/authorize.json",    to: "oauth#authorize_json", as: :authorize_json
   get  "/:connector_key/authorize",         to: "oauth#authorize",      as: :authorize
-  # Legacy monolithic-host callback — same-origin frontend/backend hosts
-  # (n8n-style). Split-origin apps point the redirect_uri at the frontend
-  # and POST to /oauth/exchange instead.
+  # Provider callback for hosts using the engine callback URL.
+  # Hosts with a separate frontend callback use /oauth/exchange instead.
   get  "/:connector_key/callback",          to: "oauth#callback",       as: :callback
 
   # App-level webhook URL (Slack, GitHub Apps, Linear, Notion, ...): one URL
   # per app, grant resolved from payload via Connector.resolve_grant_from_webhook.
   post "/:connector_key/webhook",                          to: "webhooks#receive", as: :app_webhook
 
-  # Phase 7 — multi-webhook providers route by `webhook_name` segment so
-  # `webhookMethods.default` and `webhookMethods.setup` get distinct URLs
-  # (mirrors n8n's `IWebhookDescription.name` at interfaces.ts:2600).
+  # Named webhook groups have distinct URLs, such as default and setup.
   post "/:connector_key/webhook/:webhook_name",            to: "webhooks#receive", as: :named_app_webhook
 
   # Per-grant webhook URL (Stripe, Twilio, ...): grant explicit in URL.

data/db/migrate/20260518210324_create_connectors_grants.rb

@@ -14,19 +14,12 @@ class CreateConnectorsGrants < ActiveRecord::Migration[8.1]
       t.datetime :last_used_at
       t.string   :external_account_id               # provider-side user/account id, if applicable
 
-      # Per-grant scratch storage for webhook subscriptions + polling cursors
-      # (n8n parity: `getWorkflowStaticData('node')` at interfaces.ts:1257-1274).
-      # Each `webhook_methods` group writes into its own nested hash keyed
-      # by the group name, so multi-webhook providers can persist
-      # independent state per subscription type.
+      # Per-grant scratch storage. Each webhook group uses its own nested hash
+      # for independent subscription state.
       t.jsonb    :static_data,         null: false, default: {}
 
-      # External secrets manager integration. A grant either stores its
-      # credentials inline (DB-encrypted) OR carries a lightweight
-      # `external_ref` that the host's vault adapter resolves on demand.
-      # n8n parity: `__overwrittenProperties` on the credential type
-      # (interfaces.ts:382), populated by frontend.service.ts:681-705
-      # when the external-secrets EE module is active.
+      # Managed credentials use an opaque external_ref resolved by the host.
+      # Stored credential values are encrypted by the Grant model.
       t.string   :external_ref
       t.boolean  :is_managed,          null: false, default: false
 

data/db/migrate/20260521140000_create_connectors_credential_shares.rb

@@ -1,12 +1,6 @@
 class CreateConnectorsCredentialShares < ActiveRecord::Migration[8.1]
-  # Phase 9 — credential sharing. One row per (grant, principal) pair.
-  # `principal_type` is whatever the host wires through the
-  # `Connectors.configuration.principal_resolver` block — it's almost
-  # always "User" but EE hosts may share to "Team" / "Project" / etc.
-  #
-  # n8n parity: enterprise/credentials.controller.ee.ts handles
-  # `PUT /credentials/:id/share` + `/transfer`. We give the engine the
-  # SAME storage shape without baking in host-app concepts.
+  # One credential share per (grant, principal) pair. The host defines
+  # principal types, such as User, Team or Project, through its resolver.
   def change
     create_table :connectors_credential_shares, id: :uuid do |t|
       t.references :grant, type: :uuid, null: false, foreign_key: { to_table: :connectors_grants }

data/docs/releasing.md

@@ -29,7 +29,7 @@ Create the matching GitHub environment `release`, with a deployment tag policy a
    ```sh
    bundle exec ruby script/verify_package.rb
    bundle exec gem build connectors.gemspec --strict
-   gem specification connectors-0.1.0.gem files
+   gem specification connectors-0.1.1.gem files
    ```
 
    Replace the artifact version when preparing a later release. The verification script checks public metadata, required files and documentation links, installs the gem into a temporary directory, and boots a fresh Rails host outside the checkout. It checks the shipped connector registry, migration discovery and MCP schema loading. It neither publishes nor invokes a provider. RSpec runs this same check in CI.
@@ -37,7 +37,7 @@ Create the matching GitHub environment `release`, with a deployment tag policy a
 4. Merge the reviewed release changes through a pull request after its required checks pass. Confirm CI on the merged `main` commit also passes.
 5. Confirm the RubyGems account and publisher configuration above are complete before pushing a tag.
 
-The package includes runtime code, migrations, protocol data/licenses and consumer documentation. Tests, the dummy host, development tooling, lockfile, workflows and ignored internal planning documents remain outside the gem. Develop from the source repository, not the installed package.
+The package includes runtime code, migrations, protocol data/licenses and consumer documentation. Tests, the dummy host, development tooling, lockfile and workflows remain outside the gem. Develop from the source repository, not the installed package.
 
 ## Publish the verified commit
 
@@ -45,8 +45,8 @@ Fetch the merged commit, confirm its version and green CI, then create an annota
 
 ```sh
 git fetch origin --tags
-git tag -a v0.1.0 <verified-main-commit-sha> -m "Release 0.1.0"
-git push origin v0.1.0
+git tag -a v0.1.1 <verified-main-commit-sha> -m "Release 0.1.1"
+git push origin v0.1.1
 ```
 
 Replace the SHA placeholder and version. Pushing the tag starts `.github/workflows/release.yml`. It reuses the normal CI workflow to run lint and the full RSpec suite before the publishing job starts. The publishing job verifies the tag, ancestry and package, builds the gem strictly, exchanges GitHub OIDC identity for short-lived RubyGems credentials using the official credentials action, then pushes the package. Only this job has `id-token: write`; neither job needs repository write permission.

data/lib/connectors/action.rb

@@ -1,9 +1,7 @@
 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.
+  # — Slack "post message", Resend "send email", GitHub "create issue". Each
+  # action describes its inputs, outputs and execution handler.
   #
   # The class is a value object — `ActionBuilder` materialises it from the
   # DSL, `Connector.actions` stores them, `ActionRunner` invokes them.
@@ -30,9 +28,8 @@ module Connectors
   #     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.
+    # Supported action input types. Action fields include collections and
+    # other per-execution inputs beyond the credential form types.
     ALLOWED_TYPES = %w[
       string number boolean
       options multiOptions

data/lib/connectors/action_builder.rb

@@ -1,12 +1,7 @@
 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`).
+  # Builds an Action from field, optional output, and execute declarations.
+  # Action and credential fields share CredentialSchema::Field serialization;
+  # Action::ALLOWED_TYPES defines the action-specific type set.
   class ActionBuilder
     Field = CredentialSchema::Field
 
@@ -61,10 +56,8 @@ module Connectors
       )
     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.
+    # Optional result schema for clients to discover available output fields.
+    # Uses the same field DSL as action inputs.
     def output(&block)
       raise ArgumentError, "output requires a block" if block.nil?
       collector = OutputCollector.new

data/lib/connectors/action_runner.rb

@@ -1,8 +1,7 @@
 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.
+  # connector instance's context. Returns the same normalized response
+  # envelope to HTTP controllers and direct Ruby callers.
   #
   #   result = ActionRunner.call(grant, :send_email, { "from" => "x", "to" => "y", ... })
   #   # => { status: "ok",    action: "send_email", data: { "id" => "abc-123" } }
@@ -11,9 +10,7 @@ module Connectors
   #   #      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.
+  # errors. Unexpected failures propagate to the caller.
   class ActionRunner
     OK    = "ok".freeze
     ERROR = "error".freeze
@@ -63,11 +60,8 @@ module Connectors
       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.
+      # Unknown keys do not fail validation; coerced_input drops them
+      # before invoking the execute block.
       _ = provided
     end
 

data/lib/connectors/auth_injection.rb

@@ -1,16 +1,9 @@
 module Connectors
-  # Resolves n8n-style `={{$credentials.x}}` templates inside an
-  # `IAuthenticateGeneric` properties block (n8n source:
-  # packages/workflow/src/interfaces.ts:269-288, 197-208).
+  # Resolves credential templates in declarative authentication properties.
+  # Only `$credentials.field` and bracket lookups are supported.
   #
-  # 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).
+  # Strings beginning with `=` interpolate their `{{ ... }}` segments.
+  # Other strings remain literal; general expressions are unsupported.
   module AuthInjection
     module_function
 
@@ -24,10 +17,8 @@ module Connectors
     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).
+        # Resolve both keys and values so header and query names can come
+        # from credential fields.
         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)
@@ -45,9 +36,7 @@ module Connectors
       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).
+    # Supports dot and quoted bracket lookups. Missing fields resolve to "".
     def lookup(expr, credentials)
       expr = expr.to_s.strip
       if (m = expr.match(/\A\$credentials\.([A-Za-z_][A-Za-z0-9_]*)\z/))

data/lib/connectors/client_builder.rb

@@ -15,22 +15,16 @@ module Connectors
   #   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
+  #   7. PreAuthentication                          — 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).
+    # AuthenticateGeneric applies a resolved authenticate declaration when
+    # present; otherwise the client uses the configured auth_scheme.
+    # PreAuthentication runs the optional hook when expires_at is absent or 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