Rails provider generator - Sure Docs (draft)

This guide explains how to use the Provider generators, which make it easy to add new integrations with either global or per-family scope credentials.

Quick start

Two generators available

# Per-Family Provider (each family has separate credentials)
rails g provider:family <PROVIDER_NAME> field:type[:secret] ...

# Global Provider (all families share site-wide credentials)
rails g provider:global <PROVIDER_NAME> field:type[:secret] ...

Quick examples

# Per-family: Each family has their own Lunchflow API key
rails g provider:family lunchflow api_key:text:secret base_url:string

# Global: All families share the same Plaid credentials
rails g provider:global plaid \
  client_id:string:secret \
  secret:string:secret \
  environment:string:default=sandbox

Global vs per-family: Which to use?

Use `provider:global` when:

✅ One set of credentials serves the entire application
✅ Provider charges per-application (not per-customer)
✅ You control the API account (self-hosted or managed mode)
✅ All families can safely share access
✅ Examples: Plaid, OpenAI, exchange rate services

Use `provider:family` when:

✅ Each family/customer needs their own credentials
✅ Provider charges per-customer
✅ Users bring their own API keys
✅ Data isolation required between families
✅ Examples: Lunch Flow, SimpleFIN, YNAB, personal bank APIs

Provider:family generator

Usage

rails g provider:family <PROVIDER_NAME> field:type[:secret][:default=value] ...

Reserved field names

The generator rejects field names that are already defined on the items table. Passing a reserved name raises a Thor::Error at generation time rather than producing broken migrations or inconsistent models. Reserved names include: family_id, institution_id, institution_name, institution_domain, institution_url, institution_color, status, scheduled_for_deletion, pending_account_setup, sync_start_date, raw_payload, raw_institution_payload. Note that family (without _id) is not reserved — the migration writes t.references :family, which creates family_id, so a field named family is not a collision.

Example: Adding a MyBank provider

rails g provider:family my_bank \
  api_key:text:secret \
  base_url:string:default=https://api.mybank.com \
  refresh_token:text:secret

What gets generated

This single command generates:

✅ Migration for my_bank_items and my_bank_accounts tables with credential fields
✅ Models: MyBankItem, MyBankAccount, and MyBankItem::Provided concern
✅ Adapter class for provider integration
✅ Simple manual panel view for provider settings
✅ Controller with CRUD actions and Turbo Stream support
✅ Routes
✅ Bank sync wiring: the settings controller’s FAMILY_PANELS entry and sync maps, and a provider_summary case

The last item means the provider appears under Your connections on the Bank sync page, its connection row shows a sync status, and the Sync button works — all without any manual follow-up steps. The generated item partial renders the provider’s logo with ProviderLogo. That reads the provider’s Provider::Metadata::REGISTRY entry, which the generator does not create, so add one in app/models/provider/metadata.rb. See the providers LLM guide for the fields it reads (domain, logo_text, logo_color, logo_icon) and which are used when Brandfetch has no icon or is not configured. The item partial declares visible_accounts: as a strict local. Callers must pass the accounts to display explicitly. The rendered account list uses that local; the partial can still query the item’s accounts for summary counts. Pass only the accounts you want shown:

<%= render "my_bank_items/my_bank_item",
           my_bank_item: item,
           visible_accounts: visible_card_accounts(item) %>

The generated caller uses visible_card_accounts(item) to respect the current user’s account visibility. A strict local requires an explicit argument; it does not enforce authorization, so callers must not replace the filtered list with all accounts indiscriminately.

Key characteristics

Credentials: Stored in my_bank_items table (encrypted)
Isolation: Each family has completely separate credentials
UI: Manual form panel at /settings/providers
Configuration: Per-family, self-service

Provider:global generator

Usage

rails g provider:global <PROVIDER_NAME> field:type[:secret][:default=value] ...

Example: Adding a Plaid provider

rails g provider:global plaid \
  client_id:string:secret \
  secret:string:secret \
  environment:string:default=sandbox

What gets generated

This single command generates:

✅ Migration for plaid_items and plaid_accounts tables without credential fields
✅ Models: PlaidItem, PlaidAccount, and PlaidItem::Provided concern
✅ Adapter with Provider::Configurable
❌ No controller (credentials managed globally)
❌ No view (UI auto-generated by Provider::Configurable)
❌ No routes (no CRUD needed)

Key characteristics

Credentials: Stored in settings table (global, not encrypted)
Sharing: All families use the same credentials
UI: Auto-generated at /settings/providers (self-hosted mode only)
Configuration: ENV variables or admin settings

Important notes

Credentials are shared by all families - use only for trusted services
Only available in self-hosted mode (admin-only access)
No per-family credential management needed
Simpler implementation (fewer files generated)

Comparison table

Aspect	`provider:family`	`provider:global`
Credentials storage	`provider_items` table (per-family)	`settings` table (global)
Credential encryption	✅ Yes (ActiveRecord encryption)	❌ No (plaintext in settings)
Family isolation	✅ Complete (each family has own credentials)	❌ None (all families share)
Files generated	9+ files	5 files
Migration includes credentials	✅ Yes	❌ No
Controller	✅ Yes (simple CRUD)	❌ No
View	✅ Manual form panel	❌ Auto-generated
Routes	✅ Yes	❌ No
UI location	`/settings/providers` (always)	`/settings/providers` (self-hosted only)
ENV variable support	❌ No (per-family can’t use ENV)	✅ Yes (fallback)
Use case	User brings own API key	Platform provides API access
Examples	Lunch Flow, SimpleFIN, YNAB	Plaid, OpenAI, TwelveData

What gets generated (detailed)

1. Migration

File: db/migrate/xxx_create_my_bank_tables_and_accounts.rb Creates two complete tables with all necessary fields. The generator writes the Rails version in use when it runs, taken from Rails::VERSION::MAJOR and Rails::VERSION::MINOR joined by a dot (for example, 8.1). The version in any generated migration is then fixed — it pins the semantics the migration was written against and is not rewritten by later upgrades.

class CreateMyBankTablesAndAccounts < ActiveRecord::Migration[8.1]
  def change
    # Create provider items table (stores per-family connection credentials)
    create_table :my_bank_items, id: :uuid do |t|
      t.references :family, null: false, foreign_key: true, type: :uuid
      t.string :name

      # Institution metadata
      t.string :institution_id
      t.string :institution_name
      t.string :institution_domain
      t.string :institution_url
      t.string :institution_color

      # Status and lifecycle
      t.string :status, default: "good"
      t.boolean :scheduled_for_deletion, default: false
      t.boolean :pending_account_setup, default: false

      # Sync settings
      t.datetime :sync_start_date

      # Raw data storage
      t.jsonb :raw_payload
      t.jsonb :raw_institution_payload

      # Provider-specific credential fields
      t.text :api_key
      t.string :base_url
      t.text :refresh_token

      t.timestamps
    end

    add_index :my_bank_items, :family_id
    add_index :my_bank_items, :status

    # Create provider accounts table (stores individual account data from provider)
    create_table :my_bank_accounts, id: :uuid do |t|
      t.references :my_bank_item, null: false, foreign_key: true, type: :uuid

      # Account identification
      t.string :name
      t.string :account_id

      # Account details
      t.string :currency
      t.decimal :current_balance, precision: 19, scale: 4
      t.string :account_status
      t.string :account_type
      t.string :provider

      # Metadata and raw data
      t.jsonb :institution_metadata
      t.jsonb :raw_payload
      t.jsonb :raw_transactions_payload

      t.timestamps
    end

    add_index :my_bank_accounts, :account_id
    add_index :my_bank_accounts, :my_bank_item_id
  end
end

2. Models

File: app/models/my_bank_item.rb The item model stores per-family connection credentials:

class MyBankItem < ApplicationRecord
  include Syncable, Provided, Unlinking, DestroyableLater

  enum :status, { good: "good", requires_update: "requires_update" }, default: :good

  # Encryption for secret fields
  if Rails.application.credentials.active_record_encryption.present?
    encrypts :api_key, :refresh_token, deterministic: true
  end

  validates :name, presence: true
  validates :api_key, presence: true, on: :create
  validates :refresh_token, presence: true, on: :create

  belongs_to :family
  has_one_attached :logo
  has_many :my_bank_accounts, dependent: :destroy
  has_many :accounts, through: :my_bank_accounts

  scope :active, -> { where(scheduled_for_deletion: false) }
  scope :syncable, -> { active }
  scope :ordered, -> { order(created_at: :desc) }
  scope :needs_update, -> { where(status: :requires_update) }

  def credentials_configured?
    api_key.present? && refresh_token.present?
  end

  def effective_base_url
    base_url.presence || "https://api.mybank.com"
  end
end

File: app/models/my_bank_account.rb The account model stores individual account data from the provider:

class MyBankAccount < ApplicationRecord
  include CurrencyNormalizable

  belongs_to :my_bank_item

  # Association through account_providers for linking to internal accounts
  has_one :account_provider, as: :provider, dependent: :destroy
  has_one :account, through: :account_provider, source: :account

  validates :name, :currency, presence: true

  def upsert_my_bank_snapshot!(account_snapshot)
    update!(
      current_balance: account_snapshot[:balance],
      currency: parse_currency(account_snapshot[:currency]) || "USD",
      name: account_snapshot[:name],
      account_id: account_snapshot[:id]&.to_s,
      account_status: account_snapshot[:status],
      raw_payload: account_snapshot
    )
  end
end

File: app/models/my_bank_item/provided.rb The Provided concern connects the item to its provider SDK:

module MyBankItem::Provided
  extend ActiveSupport::Concern

  def my_bank_provider
    return nil unless credentials_configured?

    Provider::MyBank.new(
      api_key,
      base_url: effective_base_url,
      refresh_token: refresh_token
    )
  end
end

3. Adapter

File: app/models/provider/my_bank_adapter.rb

class Provider::MyBankAdapter < Provider::Base
  include Provider::Syncable
  include Provider::InstitutionMetadata

  # Register this adapter with the factory
  Provider::Factory.register("MyBankAccount", self)

  def provider_name
    "my_bank"
  end

  # Build a My Bank provider instance with family-specific credentials
  def self.build_provider(family:)
    return nil unless family.present?

    # Get family-specific credentials
    my_bank_item = family.my_bank_items.where.not(api_key: nil).first
    return nil unless my_bank_item&.credentials_configured?

    # TODO: Implement provider initialization
    Provider::MyBank.new(
      my_bank_item.api_key,
      base_url: my_bank_item.effective_base_url,
      refresh_token: my_bank_item.refresh_token
    )
  end

  def sync_path
    Rails.application.routes.url_helpers.sync_my_bank_item_path(item)
  end

  def item
    provider_account.my_bank_item
  end

  def can_delete_holdings?
    false
  end

  def institution_domain
    metadata = provider_account.institution_metadata
    return nil unless metadata.present?
    metadata["domain"]
  end

  def institution_name
    metadata = provider_account.institution_metadata
    return nil unless metadata.present?
    metadata["name"] || item&.institution_name
  end

  def institution_url
    metadata = provider_account.institution_metadata
    return nil unless metadata.present?
    metadata["url"] || item&.institution_url
  end

  def institution_color
    item&.institution_color
  end
end

4. Controller

File: app/controllers/my_bank_items_controller.rb The generated controller inherits StreamExtensions through ApplicationController and uses frame_redirect_to for missing-credential exits. The account-linking flow actions (preload_accounts, select_accounts, select_existing_account) call frame_redirect_to when a required credential check fails. A plain redirect_to inside a Turbo frame follows the redirect inside the frame, so the resulting page renders inside the modal and the flash message is never shown. frame_redirect_to detects whether the request came from a Turbo frame and, when it did, renders a frame containing a turbo-stream redirect action, which causes a full-page visit instead of a frame navigation.

class MyBankItemsController < ApplicationController
  before_action :set_my_bank_item, only: [:show, :edit, :update, :destroy, :sync, :setup_accounts, :complete_account_setup]

  def create
    @my_bank_item = Current.family.my_bank_items.build(my_bank_item_params)
    @my_bank_item.name ||= "My Bank Connection"

    if @my_bank_item.save
      redirect_to settings_providers_path, notice: t(".success"), status: :see_other
    else
      render_provider_panel("my_bank", alert: @my_bank_item.errors.full_messages.join(", "))
    end
  end

  def update
    if @my_bank_item.update(my_bank_item_params)
      render_provider_panel("my_bank", notice: t(".success"))
    else
      render_provider_panel("my_bank", alert: @my_bank_item.errors.full_messages.join(", "))
    end
  end

  def destroy
    @my_bank_item.destroy_later
    redirect_to settings_providers_path, notice: t(".success", default: "Scheduled My Bank connection for deletion.")
  end

  def sync
    unless @my_bank_item.syncing?
      @my_bank_item.sync_later
    end

    respond_to do |format|
      format.html { redirect_back_or_to accounts_path }
      format.json { head :ok }
    end
  end

  # Account-linking flow actions

  def preload_accounts
    my_bank_item = Current.family.my_bank_items.first
    unless my_bank_item&.credentials_configured?
      frame_redirect_to settings_providers_path, alert: t(".no_credentials_configured")
      return
    end

    my_bank_item.sync_later unless my_bank_item.syncing?
    redirect_to select_accounts_my_bank_items_path(accountable_type: params[:accountable_type], return_to: params[:return_to])
  end

  def select_accounts
    my_bank_item = Current.family.my_bank_items.first
    unless my_bank_item&.credentials_configured?
      frame_redirect_to settings_providers_path, alert: t(".no_credentials_configured")
      return
    end

    @my_bank_accounts = my_bank_item.my_bank_accounts
                                    .left_joins(:account_provider)
                                    .where(account_providers: { id: nil })
                                    .order(:name)
  end

  def select_existing_account
    @account = Current.family.accounts.find(params[:account_id])
    @my_bank_item = Current.family.my_bank_items.first

    unless @my_bank_item&.credentials_configured?
      frame_redirect_to settings_providers_path, alert: t(".no_credentials_configured")
      return
    end

    @my_bank_accounts = @my_bank_item.my_bank_accounts
                                     .left_joins(:account_provider)
                                     .where(account_providers: { id: nil })
                                     .order(:name)
  end

  # ... (link_accounts, link_existing_account, setup_accounts, complete_account_setup)

  private

    def set_my_bank_item
      @my_bank_item = Current.family.my_bank_items.find(params[:id])
    end

    def my_bank_item_params
      params.require(:my_bank_item).permit(:name, :sync_start_date, :api_key, :base_url, :refresh_token)
    end
end

The key difference from a plain redirect_to in those credential-check guards is that frame_redirect_to uses turbo_frame_request? to detect whether the request originated inside a Turbo frame. When it did, it renders a frame that carries a turbo-stream redirect action, which exits the frame and performs a full-page visit to the target path with the alert flash intact. For requests outside a frame it falls back to a normal redirect_to.

Customization

After generation, you’ll typically want to customize three files:

1. Customize the adapter

Implement the build_provider method in app/models/provider/my_bank_adapter.rb:

def self.build_provider(family:)
  return nil unless family.present?

  # Get the family's credentials
  my_bank_item = family.my_bank_items.where.not(api_key: nil).first
  return nil unless my_bank_item&.credentials_configured?

  # Initialize your provider SDK with the credentials
  Provider::MyBank.new(
    my_bank_item.api_key,
    base_url: my_bank_item.effective_base_url,
    refresh_token: my_bank_item.refresh_token
  )
end

2. Update the model

Add custom validations, helper methods, and business logic in app/models/my_bank_item.rb:

class MyBankItem < ApplicationRecord
  include Syncable, Provided, Unlinking, DestroyableLater

  belongs_to :family

  # Validations (the generator adds basic ones, customize as needed)
  validates :name, presence: true
  validates :api_key, presence: true, on: :create
  validates :refresh_token, presence: true, on: :create
  validates :base_url, format: { with: URI::DEFAULT_PARSER.make_regexp }, allow_blank: true

  # Add custom business logic
  def refresh_oauth_token!
    # Implement OAuth token refresh logic
    provider = my_bank_provider
    return false unless provider

    new_token = provider.refresh_token!(refresh_token)
    update(refresh_token: new_token)
  rescue Provider::MyBank::AuthenticationError
    update(status: :requires_update)
    false
  end

  # Override effective methods for better defaults
  def effective_base_url
    base_url.presence || "https://api.mybank.com"
  end
end

3. Customize the view

Edit the generated panel view app/views/settings/providers/_my_bank_panel.html.erb to add custom content. StyledFormBuilder (used via styled_form_with) accepts these options on every text-type field in addition to standard HTML attributes:

Option	Description
`label:`	Label text shown above the field. Pass `true` to derive it from the field name, or a string for custom text.
`help_text:`	Hint shown below the field. Linked to the input via `aria-describedby`.
`label_tooltip:`	Tooltip icon placed beside the label with explanatory text.
`container_class:`	Extra CSS classes on the wrapper `div`.
`required:`	Adds a red asterisk to the label and the `required` HTML attribute to the input.

Example — adding a hint to the API key field:

<%= form.text_field :api_key,
    label: t(".api_key_label"),
    help_text: t(".api_key_hint"),
    type: :password %>

Fields rendered without a label (label: false or inline: true) receive the hint directly after the input, without a wrapper, so their layout stays unchanged.

Examples

Example 1: Simple API key provider

rails g provider:family coinbase api_key:text:secret

Result: Basic provider with just an API key field.

Example 2: OAuth provider

rails g provider:family stripe \
  client_id:string:secret \
  client_secret:string:secret \
  access_token:text:secret \
  refresh_token:text:secret

Then customize the adapter to implement OAuth flow.

Example 3: Complex provider

rails g provider:family enterprise_bank \
  api_key:text:secret \
  environment:string \
  base_url:string \
  webhook_secret:text:secret \
  rate_limit:integer

Then add custom validations and logic in the model:

class EnterpriseBankItem < ApplicationRecord
  # ... (basic setup)

  validates :environment, inclusion: { in: %w[sandbox production] }
  validates :rate_limit, numericality: { greater_than: 0 }, allow_nil: true

  def effective_rate_limit
    rate_limit || 100  # Default to 100 requests/minute
  end
end

Reserved field names

The generator rejects field names that conflict with columns already defined in the standard items table. Passing a reserved name raises an error at generation time rather than failing silently during db:migrate. Reserved names (cannot be used as custom fields):

Field	Reason
`institution_id`	Standard institution metadata column
`institution_name`	Standard institution metadata column
`institution_domain`	Standard institution metadata column
`institution_url`	Standard institution metadata column
`institution_color`	Standard institution metadata column
`status`	Standard lifecycle column
`scheduled_for_deletion`	Standard lifecycle column
`pending_account_setup`	Standard lifecycle column
`sync_start_date`	Standard sync column
`raw_payload`	Standard raw data column
`raw_institution_payload`	Standard raw data column
`family_id`	Foreign key (created by `t.references :family`)
`name`	Standard name column

Note that family itself is not reserved — the migration uses t.references :family which creates family_id, so a field named family does not collide. If you need to customize the behavior of a standard column, do so in the model after generation rather than re-declaring it as a custom field.

Tips & best practices

1. Always run migrations

rails db:migrate

2. Test in console

# Check if adapter is registered
Provider::Factory.adapters
# => { ... "MyBankAccount" => Provider::MyBankAdapter, ... }

# Test provider building
family = Family.first
item = family.my_bank_items.create!(name: "Test", api_key: "test_key", refresh_token: "test_refresh")
provider = Provider::MyBankAdapter.build_provider(family: family)

3. Use proper encryption

Always check that encryption is set up:

# In your model
if Rails.application.credentials.active_record_encryption.present?
  encrypts :api_key, :refresh_token, deterministic: true
else
  Rails.logger.warn "ActiveRecord encryption not configured for #{self.name}"
end

4. Implement proper error handling

def self.build_provider(family:)
  return nil unless family.present?

  item = family.my_bank_items.where.not(api_key: nil).first
  return nil unless item&.credentials_configured?

  begin
    Provider::MyBank.new(item.api_key)
  rescue Provider::MyBank::ConfigurationError => e
    Rails.logger.error("MyBank provider configuration error: #{e.message}")
    nil
  end
end

5. Add integration tests

# test/models/provider/my_bank_adapter_test.rb
class Provider::MyBankAdapterTest < ActiveSupport::TestCase
  test "builds provider with valid credentials" do
    family = families(:family_one)
    item = family.my_bank_items.create!(
      name: "Test Bank",
      api_key: "test_key"
    )

    provider = Provider::MyBankAdapter.build_provider(family: family)
    assert_not_nil provider
    assert_instance_of Provider::MyBank, provider
  end

  test "returns nil without credentials" do
    family = families(:family_one)
    provider = Provider::MyBankAdapter.build_provider(family: family)
    assert_nil provider
  end
end

Reserved field names

The provider:family generator rejects field names that collide with columns already present on every items table. Passing a reserved name raises an error at generation time rather than failing silently at db:migrate. Reserved names (cannot be used as custom fields): institution_id, institution_name, institution_domain, institution_url, institution_color, status, scheduled_for_deletion, pending_account_setup, sync_start_date, raw_payload, raw_institution_payload, family_id If you need to store data that overlaps with one of these columns, use the built-in column directly — it already exists on the generated table.

# This will raise an error at generation time:
rails g provider:family my_bank institution_id:string api_key:text:secret
# => Error: 'institution_id' is a reserved field name. Drop it from the command.

# Use the built-in column instead:
rails g provider:family my_bank api_key:text:secret

Troubleshooting

Reserved field name error

If the generator raises Thor::Error: '<field>' is a reserved field name, remove that field from the command. The items table already defines it, so declaring it again would produce a duplicate migration column and inconsistent model code. See Reserved field names for the full list.

Panel not showing

Check that FAMILY_PANELS in settings/providers_controller.rb includes an entry for the provider:

{ key: "my_bank", title: "My Bank", turbo_id: "my_bank", partial: "my_bank_panel" }

Check that the instance variable is set in the controller’s show action:
@my_bank_items = Current.family.my_bank_items.ordered.select(:id)
Check that provider_summary in app/helpers/settings_helper.rb has a "my_bank" case.

Form not submitting

Check routes are properly added: rails routes | grep my_bank
Check the panel root ID matches the turbo_id in FAMILY_PANELS: the view must have id="my_bank-providers-panel" at its root, which render_provider_panel replaces via Turbo Stream.

Encryption not working

Check credentials are configured: rails credentials:edit
Add encryption keys if missing
Or use environment variables

Reserved field name error

The generator rejects field names that collide with columns already defined on the items table. If you see a Thor::Error like:

Field "institution_id" is reserved and cannot be used as a provider field.
The standard column already serves this purpose. Remove it from your command.

Drop the named field from your command — the standard column covers it. Reserved names include: institution_id, institution_name, institution_domain, institution_url, institution_color, status, family_id, scheduled_for_deletion, pending_account_setup, sync_start_date, raw_payload, raw_institution_payload. Note that family (without _id) is not reserved — t.references :family creates family_id, so a field named family does not collide.

`NoMethodError: undefined method 'syncable'` during family sync

If a freshly generated provider raises this error and takes down the nightly family sync, the generated item model is missing the syncable scope. Add it manually:

# app/models/my_bank_item.rb
scope :syncable, -> { active }

Providers generated after the fix include this scope automatically.

Advanced: Creating a provider SDK

For complex providers, consider creating a separate SDK class:

# app/models/provider/my_bank.rb
class Provider::MyBank
  class AuthenticationError < StandardError; end
  class RateLimitError < StandardError; end

  def initialize(api_key, base_url: "https://api.mybank.com")
    @api_key = api_key
    @base_url = base_url
    @client = HTTP.headers(
      "Authorization" => "Bearer #{api_key}",
      "User-Agent" => "MyApp/1.0"
    )
  end

  def get_accounts
    response = @client.get("#{@base_url}/accounts")
    handle_response(response)
  end

  def get_transactions(account_id, start_date: nil, end_date: nil)
    params = { account_id: account_id }
    params[:start_date] = start_date.iso8601 if start_date
    params[:end_date] = end_date.iso8601 if end_date

    response = @client.get("#{@base_url}/transactions", params: params)
    handle_response(response)
  end

  private

  def handle_response(response)
    case response.code
    when 200...300
      JSON.parse(response.body, symbolize_names: true)
    when 401, 403
      raise AuthenticationError, "Invalid API key"
    when 429
      raise RateLimitError, "Rate limit exceeded"
    else
      raise StandardError, "API error: #{response.code} #{response.body}"
    end
  end
end

Summary

The per-family Provider Rails generator system provides:

✅ Fast development - Generate in seconds, not hours
✅ Consistency - All providers follow the same pattern
✅ Maintainability - Clear structure and conventions
✅ Flexibility - Easy to customize for complex needs
✅ Security - Built-in encryption for sensitive fields
✅ Documentation - Self-documenting with descriptions

Use it whenever you need to add a new provider where each family needs their own credentials.

​Quick start

​Two generators available

​Quick examples

​Global vs per-family: Which to use?

​Use provider:global when:

​Use provider:family when:

​Provider:family generator

​Usage

​Reserved field names

​Example: Adding a MyBank provider

​What gets generated

​Key characteristics

​Provider:global generator

​Usage

​Example: Adding a Plaid provider

​What gets generated

​Key characteristics

​Important notes

​Comparison table

​What gets generated (detailed)

​1. Migration

​2. Models

​3. Adapter

​4. Controller

​Customization

​1. Customize the adapter

​2. Update the model

​3. Customize the view

​Examples

​Example 1: Simple API key provider

​Example 2: OAuth provider

​Example 3: Complex provider

​Reserved field names

​Tips & best practices

​1. Always run migrations

​2. Test in console

​3. Use proper encryption

​4. Implement proper error handling

​5. Add integration tests

​Reserved field names

​Troubleshooting

​Reserved field name error

​Panel not showing

​Form not submitting

​Encryption not working

​Reserved field name error

​NoMethodError: undefined method 'syncable' during family sync

​Advanced: Creating a provider SDK

​Summary

Quick start

Two generators available

Quick examples

Global vs per-family: Which to use?

Use `provider:global` when:

Use `provider:family` when:

Provider:family generator

Usage

Reserved field names

Example: Adding a MyBank provider

What gets generated

Key characteristics

Provider:global generator

Usage

Example: Adding a Plaid provider

What gets generated

Key characteristics

Important notes

Comparison table

What gets generated (detailed)

1. Migration

2. Models

3. Adapter

4. Controller

Customization

1. Customize the adapter

2. Update the model

3. Customize the view

Examples

Example 1: Simple API key provider

Example 2: OAuth provider

Example 3: Complex provider

Reserved field names

Tips & best practices

1. Always run migrations

2. Test in console

3. Use proper encryption

4. Implement proper error handling

5. Add integration tests

Reserved field names

Troubleshooting

Reserved field name error

Panel not showing

Form not submitting

Encryption not working

Reserved field name error

`NoMethodError: undefined method 'syncable'` during family sync

Advanced: Creating a provider SDK

Summary