Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

11.5 KB
Raw Blame

Integrations Admin

Status: Implemented (2026-08-06) — see "Implementation status" Target: Spree 6.0 Depends on: 6.0-delivery-rate-provider.md (EasyPost — the first real Integration consumer), 6.0-fulfillment-and-delivery.md (pickup point providers resolve credentials here), 6.0-tax-provider.md (Avalara Integration subclass). Coordinates with: 6.0-admin-api.md, 6.0-admin-spa.md, 5.5-admin-api-key-scopes.md (new read_integrations/write_integrations scopes) Author: Damian + Claude Last updated: 2026-08-06

Implementation status (2026-08-06)

Shipped in one wave, all suites green: PreferenceSchema on Spree::Integration with registers_subclasses_via over the (already existing) Spree.integrations registry, type-registration and verify-before-activate validations on the model, the unique (store_id, type) index, and read_integrations/write_integrations API-key scopes. Admin API v3: full CRUD via the shared SubclassedResource concern (registry-resolved types, typed preference setters, masked-secret round-trip guard for free), plus GET /integrations/types (gallery source with per-store connected) and POST /:id/test. SDK: adminClient.integrations with hand-written type/params definitions and the generated Integration type. Dashboard: /settings/integrations gallery grouped by integration_group with a connect/configure sheet (PreferencesForm, active toggle, inline test-connection, destructive-confirmed disconnect), settings-nav entry, i18n in all six locales. rswag coverage + regenerated OpenAPI/CLI specs.

Two notes beyond the design below: (1) the model's type-registration validation is skipped while the registry is empty — core ships no integrations, and the admin API resolves types through the registry regardless, so the escape keeps bare-core installs and factories working; (2) Spree::Integration.api_type derives the wire shorthand from the outer module for classes named exactly Integration (SpreeEasyPost::Integration → easy_post) — the gem convention makes demodulized names collide on integration.

Summary

Make Spree::Integration the single credential surface for every provider seam — delivery rates (EasyPost), tax (Avalara), fulfillment, pickup point networks (InPost), and future gateways of any kind — and give it the admin surface it has never had: an Admin API v3 resource plus a dashboard "Integrations" settings page where a merchant sees, in one place, everything connected to the current store. The model shipped in 5.x (spree_integrations: per-store, typed, preferences, active, can_connect?) but has zero subclasses in core, no registry, no API, and no UI — every capability on it is currently unexercised. This plan is the missing half: providers stay stateless strategy objects; Integrations own the credentials; the dashboard owns the visibility.

Key Decisions (do not deviate without discussion)

  • One credential home. Provider gems ship an Spree::Integration subclass holding credentials in model preferences, plus one or more stateless provider classes that resolve it via store.integrations.active.find_by(type: ...). Providers never store credentials, and no new provider seam may invent its own credential storage (no env-var contracts, no preferences on the provider's host model). Existing exception: the Meilisearch search provider stays on MEILISEARCH_URL env config for 6.0 — it is infrastructure shared across stores, not a per-store commerce credential; migrating it is out of scope.
  • Explicit registry: Spree.integrations. Engine-defaulted array of class-name strings; gems append in an initializer (Spree.integrations << 'SpreeEasyPost::Integration'). Same shape as Spree.fulfillment_providers / Spree.delivery_method_rules. No descendants-scanning — eager-loading-dependent magic hides intent. Spree::Integration validates type inclusion against the registry on attribute change.
  • Preference schema drives the UI. Spree::Integration includes the existing Spree::PreferenceSchema concern. The types-discovery endpoint serves serialized_preference_schema; the dashboard renders forms with the existing PreferencesForm component. Secrets use :password-typed preferences and flow through the existing Spree::Preferences::Masking machinery — masked on read (•••• + last 4), masked-round-trip-guarded on write, exactly as payment method credentials work today.
  • One integration per (store, type) stays (model validation shipped; this plan adds the backing unique DB index per house rule). Multi-account support is explicitly out of scope — same deferral as 6.0-payment-method-rules.md's per-channel credentials grooming note.
  • Admin-only surface. No store serializer, no storefront exposure, ever. Secret-key access is gated by new read_integrations / write_integrations scopes; JWT access by CanCanCan on Spree::Integration.
  • Verify before activate (resolved 2026-08-06). Saving credentials never runs a network call — partial setups save fine, inactive. Flipping active: true runs can_connect? and rejects with 422 (connection_error_message in the error) on failure. Accepted trade-off: a vendor outage temporarily blocks going live (not editing); the explicit POST /:id/test endpoint remains for diagnostics at any time.
  • Gallery branding is logo_url + server-localized description (resolved 2026-08-06). Integration gems declare a class-level logo_url — an absolute URL to hosted brand assets, or a data: URI for self-contained gems — and a description (with spree.integrations.<api_type>.description Rails translations winning, so gems localize server-side; dashboard locale files are not extendable by Ruby gems). Deliberately not asset-pipeline paths: in the 6.0 split the Rails side is a data API — integration gems shipping browser images would force Propshaft onto headless hosts plus precompile hints and host-URL resolution. Accepted trade-off: hosted logos are a courtesy, not a guarantee (vendor CDNs rot, air-gapped admins) — the dashboard always falls back to a letter avatar, and self-contained gems use data URIs.
  • Connection status is ephemeral (resolved 2026-08-06). No last_checked_at/last_error columns — the test endpoint returns live results, the gallery shows stored state (active) plus on-demand test results. Accepted trade-off: no "last verified 2h ago" display without clicking test.

Design Details

Model additions (spree/core)

class Spree::Integration < Spree.base_class
  include Spree::PreferenceSchema   # preference_schema, serialized_preferences (masked)

  validate :type_must_be_registered, if: :type_changed?
end
  • Migration: add_index :spree_integrations, [:store_id, :type], unique: true (backs the existing uniqueness validation).
  • Spree.integrations / Spree.integrations= accessors over Rails.application.config.spree.integrations (default []).
  • integration_group, integration_name, integration_key, icon_path already exist on the class — the types endpoint finally consumes them.

Admin API v3 (/api/v3/admin/integrations)

Standard Admin::ResourceController CRUD plus two extras:

Endpoint Purpose
GET /integrations Connected integrations for the current store (Ransack: type, active)
GET /integrations/types Registered types: type (wire shorthand via integration_key), name, group, icon, preference_schema (password defaults nilled), and connected for the current store — the dashboard's gallery source
POST /integrations params.permit(:type, :active, preferences: {}) — flat params, type resolved from the wire shorthand against the registry only (never bare constantize)
PATCH /integrations/:id Preferences merged with the masked-round-trip guard: a submitted value carrying the mask token keeps the stored secret. Activation (active: true, on create or update) runs can_connect? and 422s on failure per the verify-before-activate decision
DELETE /integrations/:id Disconnect. Providers referencing it degrade per their own available_for_store? contract
POST /integrations/:id/test Runs can_connect?; returns { connected:, error_message: } from connection_error_message. Never persisted

Serializer (admin only): id, type (shorthand), name, group, active, preferences via serialized_preferences (masked), created_at/updated_at. Scope is current_store.integrations — cross-store ids 404.

Dashboard (/settings/integrations)

  • Settings-nav entry in the existing settings registry; <Can>-gated on integrations.
  • Gallery page: registered types grouped by integration_group (shipping, tax, …, translated via Spree.t-mirrored i18n keys), each card showing icon, name, and connected/active state — this is the "one page to see what is connected" the plan exists for.
  • Connect/configure sheet: PreferencesForm rendered from preference_schema, active toggle, "Test connection" button calling the test endpoint and surfacing error_message inline, destructive-confirmed disconnect.
  • adminClient.integrations resource in @spree/admin-sdk; full type-generation pipeline; i18n keys in all six locales.

Provider linkage

Each provider class declares self.integration_class and self.available_for_store?(store) (already specified in 6.0-delivery-rate-provider.md). Admin pickers (delivery-method provider select, tax provider select) filter on available_for_store? and deep-link to /settings/integrations when the wanted integration is not yet connected — the integrations page is the hub those flows land on.

Migration Path

  1. Core: registry + PreferenceSchema include + type-inclusion validation + unique index migration.
  2. Admin API: controller, serializer, scopes, integration specs (happy path) + controller specs (masking round-trip, cross-store 404, unregistered type rejection).
  3. SDK resource + generated types.
  4. Dashboard gallery + sheet + settings-nav entry + i18n.
  5. First consumers land with their own plans: SpreeEasyPost::Integration (delivery-rate Phase 5) and Avalara (tax). Pickup point network integrations arrive in 6.1 at the earliest (pickup work deferred, decisions.md 2026-08-06 amendment).

No data migration — the table is empty in practice (zero core subclasses exist).

Constraints on Current Work

  • New provider gems must ship an Integration subclass for credentials and register it in Spree.integrations — no env-var credential contracts for per-store providers.
  • Secrets are :password-typed preferences — anything else bypasses masking and will leak through the serializer.
  • Never constantize a client-supplied integration type — resolve through the registry.
  • Don't build per-provider credential UIs (e.g. credentials card on the delivery-method sheet) — configuration lives on the integrations page; provider pickers link to it.

Open Questions

(resolved interactively 2026-08-06 — see Key Decisions; none remain)

References

  • Model: spree/core/app/models/spree/integration.rb; table: 20250407085228_create_spree_integrations.rb
  • Schema/masking machinery: spree/core/app/models/concerns/spree/preference_schema.rb, spree/core/lib/spree/core/preferences/masking.rb
  • Types-endpoint precedent: spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rb
  • Related plans: 6.0-delivery-rate-provider.md, 6.0-fulfillment-and-delivery.md, 6.0-tax-provider.md, 6.0-payment-method-rules.md (multi-account deferral), decisions.md 2026-07-30 (reference providers), 2026-08-06 (EasyPost)