module ApiBlocks

ApiBlocks provides simple and consistent rails api extensions.

lib/join_keys.rb

ApiBlocks::Controller provides a set of default configurations for Ruby on Rails api controllers.

It sets up `ApiBlocks::Responder` as a responder, `Pundit` and controller defaults.

@example

class Api::V1::ApplicationController < ActionController::API
  include ApiBlocks::Controller

  pundit_scope :api, :v1
end

ApiBlocks::Doorkeeper implements API extensions for doorkeeper.

ApiBlocks::Doorkeeper::Invitations implements an API invitation workflow.

ApiBlocks::Doorkeeper::Invitations::Application adds `invitation_uri` validation to `Doorkeeper::Application`.

This module is automatically included on rails application startup if the invitations migrations have been ran.

@private

ApiBlocks::Doorkeeper::Invitations::Controller implements a devise invitable API controller.

ApiBlocks::Doorkeeper::Invitations::MigrationGenerator implements the Rails generator for doorkeeper invitations api migrations.

@private

ApiBlocks::Doorkeeper::Passwords implements an API reset password workflow.

ApiBlocks::Doorkeeper::Passwords::Application adds `reset_password_uri` validation to `Doorkeeper::Application`.

This module is automatically included on rails application startup if the passwords migrations have been ran.

@private

ApiBlocks::Doorkeeper::Passwords::Controller implements an API passwords reset workflow.

@example

# app/controllers/api/v1/passwords_controller.rb
class Api::V1::PasswordsController < Api::V1::ApplicationController
  include ApiBlocks::Doorkeeper::Passwords::Controller

  private

  def user_model
    User
  end
end

@example

# config/routes.rb
Rails.application.routes.draw do
  scope module: :api do
    namespace :v1 do
      resources :passwords, only: %i[create] do
        get :callback, on: :collection
        put :update, on: :collection
      end
    end
  end
end

@example

# app/models/user.rb
class User < ApplicationRecord
  include ApiBlocks::Doorkeeper::Passwords::User
end

@example

# config/initializers/devise.rb
Devise.setup do |config|
  # Configure the class responsible to send e-mails.
  config.mailer = "DeviseMailer"
end

@example

# app/mailers/devise_mailer.rb

class DeviseMailer < Devise::Mailer
  def reset_password_instructions(
    record, token, application = nil, _opts = {}
  )
    @token = token
    @application = application
  end
end

ApiBlocks::Doorkeeper::Passwords::MigrationGenerator implements the Rails generator for doorkeeper passwords api migrations.

@private

ApiBlocks::Doorkeeper::Passwords::User overrides some methods from devise recoverable module to add the dorkeeper application to the mailer.

@example

# app/models/user.rb
class User < ApplicationRecord
  include ApiBlocks::Doorkeeper::Passwords::User
end

ApiBlocks::Interactor implements a base interactor class.

It is based on `Dry::Transaction` and implements input schema parsing and validation as well as database transaction handling.

@example

class InviteUser < ApiBlocks::Interactor
  input do
    schema do
      required(:email).filled
      required(:password).filled

      optional(:first_name)
      optional(:last_name)
    end
  end

  around :database_transaction!

  step :validate_input!
  try :create_user, catch: ActiveRecord::RecordInvalid
  tee :deliver_invitation

  def create_user(params)
    Success(User.create!(params))
  end

  def deliver_invitation(user, mailer)
    mailer.accept_invitation(user)
  end
end

ApiBlocks::Railtie implements the Rails integration for ApiBlocks.

@private

ApiBlocks::Responder provides a responder with better error handling and `ApiBlocks::Interactor` through `Dry::Monads::Result` support.