connectors 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad1a8edb9dac56e6c94e54f0f926422488dfede45c390c974296cc98bdc7e4a
-  data.tar.gz: ee1826f96e2b7b9475f0030404bd307eb1a1b89ccb3b732bc04d5f1172a0c51e
+  metadata.gz: 151e674f0e09fb93928d10f222909aef9d2886ae28bf5f7c3690517807ec277e
+  data.tar.gz: a738a4ff2cdf3c265b51ad58571349687f1a5ea8dada2b0976e68fa76ad3f12a
 SHA512:
-  metadata.gz: c096165959caa7f1ae30a904054175a37d2ff048025fadf78a57cd9dd11c4b78adbf5e9b610e9678b2b7825726b02e36728b6ffd2cd917ba713b7e62d40a45d5
-  data.tar.gz: f6263fcfa7aeee54d01864c10c60c6aa9cc70080f5d4a9f85e66988a4787bf0864bb916b30e12763c9bae994ff030a846a21cf3e1a90206c0ee3330c1ff83437
+  metadata.gz: cea593fcb524afaeeb6e2ba04604bea8baf2461d0ce730314b937d21f5d310fa6af4cd3d54bf58de2c0ab2cfce71d2cb75cecfa7edf4c550092bda9a1c5d1a1e
+  data.tar.gz: 739c3a4ae3fde6598d5aacf6357c443fd9dbcd4504a7f9b5bbd204ef407053d05f2b4732a7e2cac992c0987c4df78bfd5721b5bf731eed71455402581055d12a

data/CHANGELOG.md

@@ -4,6 +4,22 @@ Changes are recorded here before release. Published packages are listed on [Ruby
 
 ## Unreleased
 
+## 0.1.1 — 2026-09-22
+
+### Fixed
+
+- Constrain JSON to 2.x for Rails 8.1 decoder compatibility; JSON 3 raises when loading encrypted credentials.
+- Update the development lockfile to Rails 8.1.3.1, Faraday 2.14.4 and OAuth2 2.0.25, and update CI actions.
+
+### Documentation
+
+- Describe connector contracts directly across guides, API metadata, source comments and test names.
+- Remove obsolete demo smoke scripts from the public source tree; supported development and package checks are documented in the contributing guide.
+
+### Upgrading
+
+- Run `bundle update connectors` to receive the JSON compatibility constraint. No database migrations or application API changes are required for this patch.
+
 ## 0.1.0 — 2026-09-22
 
 ### Added

data/CONNECTORS_FRAMEWORK.md

@@ -1,15 +1,15 @@
 # Connectors Framework Reference
 
-Developer reference for the `connectors` Rails engine. Historical n8n source references describe design inspiration; they are not a claim of current n8n parity. For installation and supported environments, start with the [README](README.md).
+Developer reference for the `connectors` Rails engine. For installation and supported environments, start with the [README](README.md).
 
-Current behavior is verified by the repository test suite. [Architecture](docs/architecture.md), [connector authoring](docs/adding-connectors.md) and [MCP support](MCP_CLIENT.md) cover the newer action and remote-tool paths.
+Current behavior is verified by the repository test suite. [Architecture](docs/architecture.md), [connector authoring](docs/adding-connectors.md) and [MCP support](MCP_CLIENT.md) describe action execution and remote tools.
 
 ---
 
 ## 1. Architecture
 
 ```
-flow-api (host Rails app)
+Host Rails application
    └─ mounts Connectors::Engine at <host-chosen prefix>   (e.g. /api/v1/connectors)
         ├─ Configuration block       (host wires owner / OAuth secrets / vault)
         ├─ Registry                  (loaded at boot from app/connectors/*/)
@@ -31,7 +31,7 @@ flow-api (host Rails app)
 
 **Mount-path independence.** The host picks where to mount the engine in `config/routes.rb`. The engine introspects the actual mount path at boot (`Connectors::Engine.mount_path`) and every URL builder (OAuth callback, default webhook URL, types-endpoint `redirect_uri` field) is wired through it. No `mount_path` configuration in initializers, no string concatenation traps — the host's routes file is the single source of truth. See §1.1 below.
 
-**No expression engine.** Phase 1 ships a tiny `{{$credentials.<field>}}` substitutor (`Connectors::AuthInjection`) scoped to credential templates. The connectors engine stays workflow-independent — anything richer belongs in the automations engine.
+**Credential templates.** `Connectors::AuthInjection` substitutes `{{$credentials.<field>}}` lookups in authentication properties. It does not evaluate general expressions or workflow logic.
 
 ### 1.1 Mount-path introspection
 
@@ -59,7 +59,7 @@ Concrete consequences:
 | Default `hook_url` for `POST /grants/:id/webhook_subscribe` | hardcoded `<host>/connectors/...` | matches the mount, whatever it is |
 | `GET /types/:name` `connector.redirect_uri` / `authorize_url` / `authorize_json_url` | hardcoded | matches the mount |
 
-The host can remount under any prefix (`/api/v2/connectors`, `/_/integrations`, etc.) and everything Just Works.
+For example, a mount under `/api/v2/connectors` produces callbacks and webhook URLs under that prefix.
 
 ---
 
@@ -82,7 +82,7 @@ Registers the connector. **Required** — every connector class calls this first
 | Arg | Type | Meaning |
 |---|---|---|
 | `key:` | symbol | machine identifier, unique per app (`:slack`) |
-| `auth:` | symbol | legacy auth scheme name (`:api_key`, `:oauth2`). Kept for back-compat with pre-Phase-1 connectors. New code should rely on `authenticate` (§3.3). |
+| `auth:` | symbol | auth scheme name (`:api_key`, `:oauth2`). A declared `authenticate` block takes precedence for request injection (§3.3). |
 | `base_url:` | string | every `client.get`/`post`/etc. is relative to this |
 | `display_name:` | string | UI label (defaults to `key.humanize`) |
 | `icon:` | string | URL or asset path |
@@ -95,7 +95,7 @@ Declares the credential form. Inner block uses `field` (see §4).
 
 ### 3.3 `authenticate type: :generic, properties: { ... }`
 
-Declarative auth injection. Mirrors n8n's `IAuthenticateGeneric` (`packages/workflow/src/interfaces.ts:269-288`). `properties` accepts any subset of:
+Declarative authentication injection into outgoing requests. `properties` accepts any subset of:
 
 ```ruby
 authenticate type: :generic, properties: {
@@ -155,7 +155,7 @@ oauth1 request_token_url: "https://api.twitter.com/oauth/request_token",
        signature_method:  "HMAC-SHA1"   # or HMAC-SHA256 / HMAC-SHA512
 ```
 
-Engine signs request-token + access-token legs inline (no `oauth-1.0a` gem). Consumer key/secret come from `Connectors.configuration.oauth_credentials_for(connector_key)` — same slot as OAuth2's client id/secret.
+The engine signs request-token and access-token exchanges. Consumer key/secret come from `Connectors.configuration.oauth_credentials_for(connector_key)` — same slot as OAuth2's client id/secret.
 
 ### 3.7 `revoke_token_url "..."` / `revoke_token { |grant| ... }`
 
@@ -173,7 +173,7 @@ end
 
 ### 3.8 `test_request method:, url:, headers:, query:, expect_status:, rules:`
 
-Declarative "Test connection". Mirrors n8n's `ICredentialTestRequest` (`interfaces.ts:340-348`).
+Connection test performed through the connector client, using its authentication and middleware.
 
 ```ruby
 test_request method: :get, url: "auth.test",
@@ -223,7 +223,7 @@ The controller calls `webhook_style` to know whether to expect `:app_level` (sin
 
 ### 3.12 `webhook_methods(:group) do ... end`
 
-Subscription lifecycle. n8n parity: `INodeType.webhookMethods.default.{checkExists, create, delete}`.
+Subscription lifecycle with `check_exists`, `create` and `delete` callbacks.
 
 ```ruby
 webhook_methods do                       # group :default (implicit)
@@ -278,7 +278,7 @@ Manual fire: `POST <mount>/grants/:id/poll` with optional `instance_key`. Return
 
 ### 3.14 `generic_auth!`, `supported_nodes :...`, `http_request_node ...`
 
-n8n credential-visibility flags (`interfaces.ts:379-381`):
+Credential visibility and HTTP-request picker metadata:
 
 ```ruby
 generic_auth!                                            # eligible for the HTTP-Request node picker
@@ -311,7 +311,7 @@ end
 
 ```ruby
 def refresh!; end                # called by AutoRefresh middleware on 401
-def poll; end                    # called by polling scheduler (workflow-roadmap)
+def poll; end                    # called by PollJob; PollRunner uses the separate polling DSL
 def handle_webhook(ctx); end     # called by DeliverWebhookJob; ctx = WebhookContext
 def validate_credentials!; end   # auto: runs CredentialSchema.validate! against grant
 ```
@@ -320,7 +320,7 @@ def validate_credentials!; end   # auto: runs CredentialSchema.validate! against
 
 ## 4. CredentialSchema Field Reference
 
-`Connectors::CredentialSchema::Field` mirrors n8n's `INodeProperties` (`interfaces.ts:1773-1812`):
+`Connectors::CredentialSchema::Field` describes an input and its rendering metadata:
 
 ```ruby
 field :api_key,
@@ -338,23 +338,26 @@ field :api_key,
       options:            [{ name: "Header", value: "header" }]
 ```
 
-`type_options` flags propagate to the editor verbatim:
-- `password: true` — masked input + redacted in serializer responses
-- `expirable: true` — UI marks the field as "will rotate"
-- `redactJsonLeaves: true` — JSON leaf values masked in error messages / logs
-- `resolvable_field: true` — field accepts `{{ }}` expressions
+`type_options` flags are serialized as form metadata for host renderers:
+
+- `password: true` — suggests a masked input; also set by `secret: true`
+- `expirable: true` — indicates a value that may rotate
+- `redactJsonLeaves: true` — suggests masking JSON leaf values
+- `resolvable_field: true` — indicates a host-resolvable input
+
+These flags do not implement token rotation, log filtering or expression evaluation. Credential response access is enforced separately by the sharing policy; owner responses can include decrypted secrets.
 
 Inheritance via `extends`:
 
 ```ruby
 credentials do
-  extends :oauth2                              # inherit OAuth2Api base fields
+  extends :oauth2                              # inherit OAuth2 base fields
   field :authorization_url, type: "hidden",    # lock provider endpoint
         default: "https://slack.com/oauth/v2/authorize"
 end
 ```
 
-Children override parents by redeclaring with the same field name. Most-specific wins. Same precedence rule n8n's credential-walker uses (`packages/cli/src/credential-types.ts:26-37`).
+Children override parents by redeclaring with the same field name. Most-specific wins.
 
 ### Schema-level DSL
 
@@ -364,7 +367,7 @@ Inside `credentials do ... end`:
 - `authenticate type: :generic, properties: {...}` — schema-level injection (inherited by every connector that `extends` this schema)
 - `generic_auth!` — mark eligible for HTTP-Request node
 - `display_name "Bearer Auth"` — UI label for the credential type itself
-- `documentation_url "httprequest"` — n8n docs slug
+- `documentation_url "https://provider.example/docs/auth"` — documentation link
 
 ---
 
@@ -384,7 +387,7 @@ Connectors.configure do |c|
   }
 
   # ---- Optional: webhook dispatch hook -----------------------------------
-  c.on_webhook = ->(event) { Inbox::IngestJob.perform_later(event.id) }
+  c.on_webhook = ->(event) { ProcessWebhookJob.perform_later(event.id) }
 
   # ---- Optional: sharing principals (host middleware supplies trusted owner) ----------------------------
   c.principal_resolver = ->(ctrl) {
@@ -392,7 +395,7 @@ Connectors.configure do |c|
     owner ? [[owner.class.name, owner.id]] : []
   }
 
-  # ---- Optional: external secrets manager (Phase 10) ---------------------
+  # ---- Optional: external secrets manager ---------------------
   c.secrets_resolver           = ->(grant) { vault.read(grant.external_ref) }
   c.secrets_managed_fields_for = ->(key)   { { slack: %w[client_secret] }.fetch(key.to_sym, []) }
 end
@@ -400,6 +403,8 @@ end
 
 The Rack owner entry in this example must be populated by trusted host authentication middleware; engine controllers do not inherit host controller callbacks. Slack/Twitter configuration here illustrates custom OAuth connectors, not shipped profiles.
 
+`ProcessWebhookJob` and `vault` are examples supplied by the host.
+
 All callables are invoked with `Connectors.configuration.<name>.call(...)` — the engine never invokes host constants directly.
 
 ---
@@ -408,16 +413,16 @@ All callables are invoked with `Connectors.configuration.<name>.call(...)` — t
 
 Registered on engine boot in `Connectors::CredentialTypeRegistry`. Connectors `extends` any of these.
 
-| Key | n8n source | Engine status |
-|---|---|---|
-| `:oauth2` | `OAuth2Api.credentials.ts:1-238` | ✅ all 3 grant types + JWE form fields |
-| `:oauth1_api` | `OAuth1Api.credentials.ts:1-72` | ✅ HMAC-SHA1/256/512 |
-| `:http_basic_auth` | `HttpBasicAuth.credentials.ts` | ✅ Basic header via `auth:` shortcut |
-| `:http_bearer_auth` | `HttpBearerAuth.credentials.ts` | ✅ Authorization: Bearer |
-| `:http_header_auth` | `HttpHeaderAuth.credentials.ts` | ✅ user-named header (templated key) |
-| `:http_query_auth` | `HttpQueryAuth.credentials.ts` | ✅ user-named query param |
-| `:http_digest_auth` | `HttpDigestAuth.credentials.ts` | ⚠️ schema only (Faraday-Digest gem TBD) |
-| `:http_custom_auth` | `HttpCustomAuth.credentials.ts` | ⚠️ schema only (runtime in Custom-API-Call node) |
+| Key | Support |
+|---|---|
+| `:oauth2` | Authorization code, client credentials and PKCE flows. JWE fields are form metadata only; no JWE decryption. |
+| `:oauth1_api` | HMAC-SHA1, HMAC-SHA256 and HMAC-SHA512 signing. |
+| `:http_basic_auth` | Basic authentication through the `auth:` shortcut. |
+| `:http_bearer_auth` | Authorization bearer token. |
+| `:http_header_auth` | Credential-defined header name and value. |
+| `:http_query_auth` | Credential-defined query parameter name and value. |
+| `:http_digest_auth` | Form schema only; no digest challenge handling. |
+| `:http_custom_auth` | Form schema only; no runtime injection of custom JSON. |
 
 ---
 
@@ -437,7 +442,7 @@ One row = one authorized account. Columns:
 | `expires_at`, `last_used_at` | datetime | |
 | `external_account_id` | string | denormalized provider-side id for webhook routing |
 | `static_data` | jsonb | per-group scratch (webhook + polling cursor state) |
-| `external_ref`, `is_managed` | string + bool | external secrets manager (Phase 10) |
+| `external_ref`, `is_managed` | string + bool | external secrets manager |
 
 Methods:
 
@@ -539,9 +544,9 @@ All persist a `WebhookEvent` and enqueue `DeliverWebhookJob` → calls `Connecto
 
 ---
 
-## 9. `WebhookContext` (Phase 7)
+## 9. `WebhookContext`
 
-Passed to `Connector#handle_webhook`. Mirrors n8n's `IWebhookFunctions` (`interfaces.ts:1327-1350`).
+Passed to `Connector#handle_webhook` with the captured request data and persisted event.
 
 ```ruby
 def handle_webhook(ctx)
@@ -632,7 +637,7 @@ POST /credentials/:id/revoke    → revoke_token block OR RFC 7009 POST to revok
 
 ---
 
-## 12. Webhook Subscription Lifecycle (Phase 6)
+## 12. Webhook Subscription Lifecycle
 
 ```
 POST /grants/:id/webhook_subscribe   (optional: webhook_name, hook_url)
@@ -652,7 +657,7 @@ Default `hook_url` is computed from `host_base_url` + `connector_key` + grant_id
 
 ---
 
-## 13. Polling (Phase 8)
+## 13. Polling
 
 ```
 POST /grants/:id/poll
@@ -666,7 +671,7 @@ The diagram shows the legacy call without an instance key. For independent consu
 
 ---
 
-## 14. Sharing (Phase 9)
+## 14. Sharing
 
 Role hierarchy: `viewer (0) < editor (1) < owner (2)`. HTTP credential access uses `GrantAccess#find_visible_grant!(id, min_role:)` and `GrantPolicy`; MCP services enforce the same roles through `MCP::Access`. Direct REST Ruby callers must authorize their selected grant.
 
@@ -678,7 +683,7 @@ Index returns the union. Show/update/destroy escalate the minimum role required.
 
 ---
 
-## 15. External Secrets (Phase 10)
+## 15. External Secrets
 
 ```
 grant.is_managed? + grant.external_ref
@@ -732,68 +737,18 @@ end
 ```
 
 Patterns used throughout `spec/connectors/`:
-- **Anonymous classes** for per-spec test connectors → registry cleanup in `after`
+- **Anonymous classes** for per-spec test connectors → registry isolation in the RSpec setup
 - **`WebMock`** for outbound HTTP
 - **`stub_request(...)` with `.with(headers: ...)`** verifies the auth-injecting middleware did its job
 - **`Connectors::OAuth::State.decode(token)`** to peek inside the encrypted state for round-trip testing
 
 ---
 
-## 18. Reference Index
-
-Every n8n source citation used across the engine:
-
-```
-packages/workflow/src/interfaces.ts
-  :197-208   IRequestOptionsSimplifiedAuth (authenticate properties shape)
-  :269-288   IAuthenticateGeneric          (declarative auth shape)
-  :340-348   ICredentialTestRequest        (test_request)
-  :350-354   ICredentialHttpRequestNode    (http_request_node)
-  :356-382   ICredentialType               (envelope: name, displayName, etc.)
-  :374-377   preAuthentication             (hook)
-  :379-381   genericAuth/supportedNodes/httpRequestNode
-  :382       __overwrittenProperties       (managed fields)
-  :1257-1274 getWorkflowStaticData         (static_data parity)
-  :1327-1350 IWebhookFunctions             (WebhookContext)
-  :1561-1584 NodePropertyTypes             (field type enum)
-  :1730-1771 IDisplayOptions + _cnd        (show/hide)
-  :1773-1812 INodeProperties               (field model)
-  :2017      webhookMethods                (declaration site)
-  :2060      polling                       (poll() method)
-  :2091-2095 webhookMethods.default        (checkExists/create/delete)
-  :2600      IWebhookDescription           (named-group routing)
-
-packages/cli/src/credential-types.ts:26-37   extends walker
-
-packages/cli/src/credentials/credentials.controller.ts:67-411   CRUD endpoints
-                                              :100-111   GET /new (unique default name)
-                                              :141-152   POST /test
-
-packages/cli/src/controllers/oauth/oauth1-credential.controller.ts:43-101   OAuth1 callback
-packages/cli/src/controllers/oauth/oauth2-credential.controller.ts:26-37   authorize.json
-
-packages/cli/src/oauth/oauth.service.ts:511-525, 578-586, 765-825   OAuth2 grant types + PKCE
-                                       :601-700                      OAuth1 generate auth uri
-                                       :528, :690                    redirect URI computation
-
-packages/cli/src/services/frontend.service.ts:681-705   __overwrittenProperties population
-                                              :707-711   __skipManagedCreation
-
-packages/cli/src/webhooks/webhook.service.ts:418   IWebhookFunctions consumption
-
-packages/nodes-base/credentials/
-  OAuth2Api.credentials.ts:1-238       canonical OAuth2 (incl. JWE fields :208-237)
-  OAuth1Api.credentials.ts:1-72        canonical OAuth1
-  HttpBasicAuth.credentials.ts         basic
-  HttpBearerAuth.credentials.ts        bearer
-  HttpHeaderAuth.credentials.ts        user-named header
-  HttpQueryAuth.credentials.ts         user-named query
-  HttpDigestAuth.credentials.ts        digest
-  HttpCustomAuth.credentials.ts        custom JSON
-  CrowdStrikeOAuth2Api.credentials.ts:62-76   preAuthentication reference
-  SlackApi.credentials.ts:56-71               test_request reference
-
-packages/nodes-base/nodes/
-  Postmark/PostmarkTrigger.node.ts:114-247    webhookMethods reference
-  Google/Gmail/GmailTrigger.node.ts:65, 281-553   polling reference
-```
+## 18. Further Reading
+
+- [Installation and host setup](README.md)
+- [Architecture and execution boundaries](docs/architecture.md)
+- [Adding a connector](docs/adding-connectors.md)
+- [Remote MCP connections](MCP_CLIENT.md)
+- [HTTP API contract](openapi.yaml)
+- [Development and testing](CONTRIBUTING.md)

data/MCP_CLIENT.md

@@ -2,11 +2,11 @@
 
 The engine consumes remote MCP **2026-07-28** servers through Streamable HTTP. It supports public servers, bearer tokens, custom authentication headers, and user OAuth with discovery, PKCE, registration, refresh and scope upgrades. Tools remain scoped to their grant; they are not added to the global connector registry.
 
-The implementation uses public helpers from `mcp` **1.6.0**, `json_schemer` **2.5**, and `event_stream_parser` **1.0**. Its durable OAuth coordinator and HTTP transport are owned by this engine. The SDK's synchronous OAuth flow and high-level tool projection did not meet the reviewed requirements. No SDK private methods are patched or invoked. Server result types are validated against the vendored, versioned official schema; its source and license are in [protocol/README.md](lib/connectors/mcp/protocol/README.md).
+The implementation uses public helpers from `mcp` **1.6.0**, `json_schemer` **2.5**, and `event_stream_parser` **1.0**. The engine implements durable OAuth coordination and HTTP transport, using only public SDK interfaces. Server result types are validated against the vendored, versioned official schema; its source and license are in [protocol/README.md](lib/connectors/mcp/protocol/README.md).
 
 ## Installation and host setup
 
-Run `bundle install` and the host's migrations. The new migration creates encrypted, expiring authorization and interaction records, with PostgreSQL foreign keys and one-time claims. Existing connector tables and credentials are preserved.
+Run `bundle install` and the host's migrations. Migrations create encrypted, expiring authorization and interaction records, with PostgreSQL foreign keys and one-time claims.
 
 Follow the [host installation guide](README.md#installation), including encryption and trusted authentication middleware. Configure the engine's existing owner/principal resolvers. These remain the authentication boundary; callers must never supply their own trusted principal list through request parameters.
 
@@ -74,9 +74,9 @@ The named connector fixes the official endpoint to `https://mcp.clickup.com/mcp`
 
 `GET /connectors/types/clickup` exposes `connector.mcp` metadata with endpoint, authentication mode, protocol version and grant-scoped URL templates. Replace `:id` with the created credential ID. `connector.redirect_uri` uses the same callback resolver as authorization. The generic MCP type exposes the same workflow metadata, with a user-configured endpoint and authentication mode.
 
-**Evidence and validation (2026-09-22):** [ClickUp's official documentation](https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server) specifies the endpoint and OAuth-only authentication. Its live 401 challenge points to [protected-resource metadata](https://mcp.clickup.com/.well-known/oauth-protected-resource/mcp), advertising `read` and `write` scopes. Its [authorization-server metadata](https://mcp.clickup.com/.well-known/oauth-authorization-server) advertises S256 PKCE, dynamic registration, public-client token authentication and required callback issuer identification. It advertises `authorization_code` without `refresh_token`; registration requests respect that metadata. Endpoints and scopes are discovered at runtime, not copied into provider-specific OAuth code.
+**Provider discovery:** [ClickUp's official documentation](https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server) specifies the endpoint and OAuth-only authentication. Its live 401 challenge points to [protected-resource metadata](https://mcp.clickup.com/.well-known/oauth-protected-resource/mcp), advertising `read` and `write` scopes. Its [authorization-server metadata](https://mcp.clickup.com/.well-known/oauth-authorization-server) advertises S256 PKCE, dynamic registration, public-client token authentication and required callback issuer identification. It advertises `authorization_code` without `refresh_token`; registration requests respect that metadata. Endpoints and scopes are discovered at runtime, not copied into provider-specific OAuth code.
 
-Request specs use captured public metadata and simulated registration/token/tool responses. The synthetic tool in those specs is explicitly a fixture. Live verification has covered public discovery and a demo owner completing consent with encrypted credential storage. Authenticated tool discovery/invocation against that Workspace has not been verified by the automated fixture suite.
+Request specs use captured public metadata and simulated registration, token and tool responses. Synthetic tools are fixtures, not a fixed catalog of ClickUp capabilities. Automated tests do not authorize or invoke tools against a live ClickUp account.
 
 ## Discover, invoke and resume
 
@@ -158,7 +158,7 @@ This release targets **2026-07-28 remote tools**. It does not advertise historic
 
 ## Validation
 
-Validated on 2026-09-22 after packaging and documentation review: **543 examples, 0 failures** (random seed `17450`, frozen lockfile), **200 Ruby files with no RuboCop offenses**, and a strict gem build plus isolated installation/boot check. This includes the existing connector regression suite.
+The [contributing guide](CONTRIBUTING.md) describes the test environment and package verification. CI runs RSpec, RuboCop and an isolated installation/boot check.
 
 RSpec covers protocol/schema contracts, authentication/registration, access isolation, secret serialization, real PostgreSQL concurrency, durable resume, real chunked SSE and idle cancellation. Interoperability runs against:
 

data/README.md

@@ -9,23 +9,25 @@ A mountable Rails engine for connecting accounts to provider APIs and remote MCP
 | Component | Requirement | Validation baseline |
 | --- | --- | --- |
 | Ruby | 3.2 or later | Ruby 3.4.8 locally and in the CI configuration |
-| Rails | 8.1.3 or later in the 8.1 series | Rails 8.1.3 |
+| Rails | 8.1.3 or later in the 8.1 series | Rails 8.1.3.1 |
 | Database | PostgreSQL 13+; migrations use UUIDs, JSONB and partial indexes | CI targets PostgreSQL 16 |
 | Identity | Persisted owner model with UUID primary keys; sharing principals also use UUIDs | Dummy `Owner` model in tests |
 | Encryption | Host-configured Active Record Encryption keys and stable Rails `secret_key_base` | Synthetic keys in tests |
 
 The declared Ruby minimum matches Rails' requirement; it is not a claim that every Ruby/OS combination has been tested. SQLite, MySQL and integer owner IDs are not supported by the shipped migrations. Install the host's PostgreSQL adapter (`pg`) in its Gemfile.
 
+JSON is constrained to 2.x because Rails 8.1's decoder is incompatible with JSON 3's argument signature.
+
 ## Installation
 
 For a published release, add to your host's Gemfile:
 
 ```ruby
-gem "connectors", "~> 0.1.0"
+gem "connectors", "~> 0.1.1"
 gem "pg"
 ```
 
-Then run `bundle install`. Before the first publication, or to test unreleased changes, use `gem "connectors", git: "https://github.com/jackhelio/connectors.git", ref: "<reviewed-commit-sha>"` instead, replacing the ref with an actual reviewed commit. Local development can use `gem "connectors", path: "../connectors"`. See [release checks](docs/releasing.md).
+Then run `bundle install`. To test unreleased changes, use `gem "connectors", git: "https://github.com/jackhelio/connectors.git", ref: "<reviewed-commit-sha>"` instead, replacing the ref with an actual reviewed commit. Local development can use `gem "connectors", path: "../connectors"`. See [release checks](docs/releasing.md).
 
 Mount the engine in `config/routes.rb`:
 

data/app/connectors/gmail/api.rb

@@ -1,10 +1,6 @@
 module Gmail
-  # Shared HTTP layer for every Gmail action. Mirrors n8n's
-  # `googleApiRequest` / `googleApiRequestAllItems` in
-  # `packages/nodes-base/nodes/Google/Gmail/GenericFunctions.ts` —
-  # one entry point that normalizes Google-specific errors into our
-  # `Connectors::ApiError` hierarchy with user-friendly messages,
-  # plus an auto-paginating variant for `*.list` endpoints.
+  # Shared HTTP layer for Gmail actions. Normalizes provider errors into
+  # the Connectors::ApiError hierarchy and paginates list endpoints.
   module Api
     module_function
 
@@ -29,8 +25,7 @@ module Gmail
       raise translate(e, resource: resource)
     end
 
-    # Walks `nextPageToken` until exhausted; concatenates the array at
-    # `property_name`. Matches n8n's signature so the porting is mechanical.
+    # Walks `nextPageToken` until exhausted and concatenates `property_name` arrays.
     def request_all(client, property_name, method, path, body: nil, query: nil, resource: "resource", page_size: 100)
       items = []
       q     = (query || {}).dup
@@ -47,9 +42,8 @@ module Gmail
       items
     end
 
-    # n8n's `googleApiRequest` rescue ladder — translated to our types.
-    # When a translation matches, we raise a new ApiError with the
-    # user-meaningful message; otherwise the original passes through.
+    # Translate recognized provider errors into actionable messages.
+    # Unrecognized errors pass through unchanged.
     def translate(error, resource:)
       status  = error.respond_to?(:status) ? error.status.to_i : 0
       body    = error.respond_to?(:body) ? error.body : nil
@@ -73,9 +67,7 @@ module Gmail
           status: status, body: body
         )
       when 409
-        # n8n parity: any 409 on the label resource is treated as a
-        # name collision — Gmail's API doesn't return 409 for any other
-        # reason on /users/me/labels.
+        # Treat a label conflict as a name collision.
         if resource.to_s == "label"
           raise Connectors::ApiError.new("Label name already exists", status: status, body: body)
         end

data/app/connectors/gmail/connector.rb

@@ -4,16 +4,9 @@ require_dependency Connectors::Engine.root.join("app/connectors/gmail/mime_parse
 require_dependency Connectors::Engine.root.join("app/connectors/gmail/polling.rb").to_s
 
 module Gmail
-  # Gmail OAuth2 connector. Talks to gmail.googleapis.com using a Bearer
-  # access_token. Auth is the standard Google OAuth2 redirect dance with
-  # PKCE (Google enforces it for confidential clients) and refresh_token
-  # rotation. Per Jackson's call: the scope set declared here is a
-  # SUGGESTION — the host can override per-grant by passing `?scope=...`
-  # to /authorize, so multi-tenant apps can ask for narrower / wider sets.
-  #
-  # n8n parity: packages/nodes-base/credentials/GmailOAuth2.credentials.ts
-  # + packages/nodes-base/nodes/Google/Gmail/v2/GmailV2.node.ts. Action
-  # surface mirrors n8n's Message / Label / Thread / Draft resources.
+  # Gmail OAuth2 connector with PKCE and refresh-token support.
+  # The declared scopes are defaults; hosts can override them with the
+  # `scope` parameter when starting authorization.
   class Connector < Connectors::Connector
     DEFAULT_SCOPES = [
       "openid",
@@ -94,13 +87,8 @@ module Gmail
 
     test_request method: :get, url: "users/me/profile"
 
-    # =========================================================================
-    # POLLING TRIGGER — Gmail-as-trigger via users.messages.list?q=after:<ts>
-    # n8n parity: packages/nodes-base/nodes/Google/Gmail/GmailTrigger.node.ts
-    # Cursor: { last_checked_at: <unix>, possible_duplicates: [<id>, ...] }
-    # Filters supplied by the workflow author at runtime (passed through
-    # `grant.static_data["polling"]["filters"]` if set, otherwise nil).
-    # =========================================================================
+    # Polls users.messages.list using a timestamp cursor and duplicate IDs.
+    # Filters come from the polling state supplied by PollRunner.
     polling do |grant, sd|
       Gmail::Polling.new(grant, sd).run
     end
@@ -144,7 +132,7 @@ module Gmail
 
     action :reply_to_message,
            display_name: "Reply to Email",
-           description:  "Reply to an existing message, preserving thread + In-Reply-To/References headers (mirrors n8n's `Message > Reply`)." do
+           description:  "Reply to an existing message, preserving thread + In-Reply-To/References headers." do
       field :message_id, type: "string", display_name: "Message ID", required: true,
             description: "The Gmail id of the message you're replying to."
       field :html, type: "string", display_name: "HTML Body",
@@ -560,8 +548,8 @@ module Gmail
 
     # =========================================================================
     # API METHODS — thin wrappers around Gmail REST endpoints. Actions
-    # delegate to these; downstream automations and curl users can call
-    # them directly via `grant.connector.<method>`.
+    # delegate to these methods; authorized Ruby callers can use
+    # `grant.connector.<method>` directly.
     # =========================================================================
 
     def send_message(to:, subject:, html: nil, text: nil,
@@ -590,9 +578,8 @@ module Gmail
       normalize_message(response)
     end
 
-    # n8n parity: packages/nodes-base/nodes/Google/Gmail/utils/replyToEmail.ts
-    # Fetches the parent message's headers (Message-ID, Subject, From, To,
-    # Reply-To), assembles a properly threaded reply via MimeBuilder, sends.
+    # Fetches the parent message's headers and sends a threaded reply
+    # using MimeBuilder.
     def reply_to_message(message_id:, html: nil, text: nil,
                           cc: nil, bcc: nil, sender_name: nil,
                           reply_to_sender_only: false,
@@ -615,7 +602,7 @@ module Gmail
       subject     = headers["subject"].to_s
       reply_subject = subject.start_with?(/re:\s/i) ? subject : "Re: #{subject}"
 
-      # Build the To: list — same precedence rules as n8n's replyToEmail.
+      # Apply sender/recipient flags, prefer Reply-To over From, and exclude self.
       profile = Api.request(client, :get, "users/me/profile", resource: "profile")
       my_email = profile["emailAddress"].to_s
 

data/app/connectors/gmail/mime_builder.rb

@@ -19,9 +19,6 @@ module Gmail
   #   - Subject + From/To/Cc display-name phrases: RFC 2047 encoded-word
   #   - Attachment filenames: RFC 2231 continuation (filename*=UTF-8''…)
   #   - Bodies: base64 transfer-encoded UTF-8
-  #
-  # n8n parity: their Gmail node uses nodemailer's mail-composer for the
-  # same job. We hand-roll because Gmail only needs the simple subset.
   class MimeBuilder
     CRLF = "\r\n".freeze
 

data/app/connectors/gmail/mime_parser.rb

@@ -2,8 +2,7 @@ require "base64"
 
 module Gmail
   # Parses Google's `messages.get?format=full` payload tree into a clean,
-  # downstream-friendly shape. Mirrors the work `parseRawEmail` does in
-  # n8n's `Gmail/GenericFunctions.ts` (which delegates to mailparser).
+  # normalized message envelope.
   #
   # Google returns:
   #   { payload: {

data/app/connectors/gmail/polling.rb

@@ -1,10 +1,9 @@
 module Gmail
   # Polling trigger logic. Invoked once per scheduler tick by
-  # `Connectors::PollRunner.run(grant)`, which threads in the per-grant
-  # scratch hash stored at `grant.static_data["polling"]`.
+  # `Connectors::PollRunner.run`, which supplies isolated state when an
+  # instance_key is provided, or per-grant polling state otherwise.
   #
-  # n8n parity: `packages/nodes-base/nodes/Google/Gmail/GmailTrigger.node.ts`.
-  # Key invariants we copy 1:1:
+  # Cursor and filtering behavior:
   #
   #   * Cursor = `last_checked_at` (unix seconds). First-ever poll bootstraps
   #     the cursor to `now` and emits nothing.
@@ -19,9 +18,7 @@ module Gmail
   #     SENT and INBOX when the user is the recipient; we want the inbound
   #     copy, not the outbound).
   #
-  # Filters are passed via `grant.static_data["polling"]["filters"]` so the
-  # workflow author can configure them per-trigger when the automations
-  # engine hooks this up:
+  # Filters are read from the supplied polling state under "filters":
   #
   #   {
   #     "q"               => "from:boss has:attachment",  # raw Gmail search
@@ -94,9 +91,7 @@ module Gmail
 
     private
 
-    # Gmail search syntax. n8n's prepareQuery is the reference; the order
-    # of clauses doesn't matter to Gmail, but keep the same join scheme so
-    # diffs against n8n are easy to read.
+    # Combine the cursor boundary and configured Gmail search filters.
     def build_query
       qs = {}
       qs["labelIds[]"]      = Array(@filters["label_ids"]) if @filters["label_ids"]
@@ -110,12 +105,10 @@ module Gmail
       status = @filters["read_status"].to_s
       q_parts << "is:#{status}" if status == "unread" || status == "read"
 
-      # Boundary-inclusive `after:` — same behavior n8n leans on; we
-      # de-dupe via possible_duplicates rather than narrowing the window.
+      # Include the cursor boundary and suppress previously emitted IDs.
       q_parts << "after:#{@sd['last_checked_at']}"
 
-      # `-in:scheduled` matches n8n's v1.4+ guard (scheduled-send drafts
-      # appear in users.messages.list but aren't real inbound mail yet).
+      # Exclude scheduled messages from inbound polling.
       q_parts << "-in:scheduled"
 
       qs[:q] = q_parts.join(" ")