propel_api 0.1.1

data/lib/generators/propel_api/templates/controllers/api_controller_propel_facets.rb

@@ -0,0 +1,76 @@
+class <%= api_controller_class_name %> < ApplicationController
+  include HasScope
+  include Pagy::Backend
+  include FacetRenderer
+  include StrongParamsHelper
+  include PropelAuthentication
+
+  before_action :authenticate_user
+  before_action :set_resource, only: [:show, :update, :destroy]
+
+  # Connect default facets to actions - can be overridden in subclasses
+  connect_facet :short, actions: [:index]
+  connect_facet :details, actions: [:show, :update, :create]
+
+  def index
+    @pagy, resources = pagy(apply_scopes(resource_class.all))
+    render json: { 
+      data: resources.map { |resource| resource_json(resource) },
+      pagination: pagy_metadata(@pagy)
+    }
+  end
+
+  def show
+    render json: { data: resource_json(@resource) }
+  end
+
+  def create
+    @resource = resource_class.new(resource_params)
+    if @resource.save
+      render json: { data: resource_json(@resource) }, status: :created
+    else
+      render json: { errors: @resource.errors }, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    if @resource.update(resource_params)
+      render json: { data: resource_json(@resource) }
+    else
+      render json: { errors: @resource.errors }, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @resource.destroy
+    head :no_content
+  end
+
+  private
+
+  def resource_class
+    @resource_class ||= controller_name.classify.constantize
+  end
+
+  def set_resource
+    @resource = resource_class.find(params[:id])
+  end
+
+  # resource_params method is provided by StrongParamsHelper concern
+  # Define permitted parameters in your individual controllers using:
+  #   permitted_params :field1, :field2, :field3
+  #
+  # Example for a UsersController:
+  #   permitted_params :username, :email_address, :first_name, :last_name
+
+  def pagy_metadata(pagy)
+    {
+      current_page: pagy.page,
+      per_page: pagy.items,
+      total_pages: pagy.pages,
+      total_count: pagy.count,
+      next_page: pagy.next,
+      prev_page: pagy.prev
+    }
+  end
+end

data/lib/generators/propel_api/templates/controllers/example_controller.rb.tt

@@ -0,0 +1,96 @@
+# Example controller showing how to use the generated Api::ApiController
+#
+# This file demonstrates proper usage of both JSON Facet and Graphiti patterns.
+# Choose the pattern that matches your serialization engine selection.
+
+<% if @engine == 'json_facet' -%>
+# JSON Facet Controller Example
+# ============================
+# Generate this controller with:
+#   rails generate controller api/<%= @resource_name.pluralize %> --no-helper --no-assets --no-view-specs
+#
+# Then replace the generated content with:
+
+module Api
+  class <%= @resource_name.pluralize.camelize %>Controller < Api::ApiController
+    # Define which parameters are allowed for <%= @resource_name %> creation/updates
+    # This uses the StrongParamsHelper concern from the base controller
+    permitted_params :name, :description, :status # Replace with your <%= @resource_name.downcase %> attributes
+
+    # Optional: Override facet connections if needed
+    # (otherwise uses defaults from parent: :short for index, :details for show/create/update)
+    connect_facet :summary, actions: [:index]
+    connect_facet :full, actions: [:show, :create, :update]
+
+    # Optional: Add scopes using has_scope (if using Ransack or similar)
+    # has_scope :by_status
+    # has_scope :search, using: :name_or_description_cont
+
+    # All CRUD methods are inherited from Api::ApiController
+    # Override them here if you need custom behavior:
+    #
+    # def index
+    #   # Custom index logic
+    #   super
+    # end
+    #
+    # def create
+    #   # Custom creation logic
+    #   @resource = resource_class.new(resource_params)
+    #   @resource.user = current_user # Example: set current user
+    #   
+    #   if @resource.save
+    #     render json: { data: resource_json(@resource) }, status: :created
+    #   else
+    #     render json: { errors: @resource.errors }, status: :unprocessable_entity
+    #   end
+    # end
+  end
+end
+
+<% elsif @engine == 'graphiti' -%>
+# Graphiti Controller Example
+# ===========================
+# 1. First generate the Graphiti resource:
+#    rails generate graphiti:resource <%= @resource_name %>
+#
+# 2. Generate this controller with:
+#    rails generate controller api/<%= @resource_name.pluralize %> --no-helper --no-assets --no-view-specs
+#
+# 3. Replace the generated content with:
+
+module Api
+  class <%= @resource_name.pluralize.camelize %>Controller < Api::ApiController
+    # Specify the Graphiti resource class for this controller
+    self.resource = <%= @resource_name %>Resource
+
+    # Alternative: Override the resource method instead
+    # private
+    # 
+    # def resource
+    #   <%= @resource_name %>Resource
+    # end
+
+    # All CRUD methods are inherited from Api::ApiController
+    # Override them here if you need custom behavior:
+    #
+    # def create
+    #   # Custom creation logic before save
+    #   resource_instance = resource.build(params)
+    #   resource_instance.data.user = current_user # Example: set current user
+    #   
+    #   if resource_instance.save
+    #     respond_with(resource_instance, status: :created)
+    #   else
+    #     respond_with(resource_instance.errors, status: :unprocessable_entity)
+    #   end
+    # end
+  end
+end
+
+# Don't forget to update your routes in config/routes.rb:
+#   namespace :api do
+#     resources :<%= @resource_name.pluralize.underscore %>
+#   end
+
+<% end -%> 

data/lib/generators/propel_api/templates/scaffold/facet_controller_template.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class <%= controller_class_name_with_namespace %>Controller < <%= api_controller_class_name %>
+  # Define which parameters are allowed for <%= class_name %> creation/updates
+  # This uses the StrongParamsHelper concern from the base controller
+  permitted_params <%= permitted_param_names.map { |attribute| ":#{attribute}" }.join(', ') %>
+
+  # Connect facets to actions - customize as needed for your <%= class_name.downcase %> model
+  # Default facets (:short for index, :details for show/create/update) are inherited from parent
+  # Uncomment and customize these lines if you want different facet connections:
+  # connect_facet :summary, actions: [:index]
+  # connect_facet :full, actions: [:show, :create, :update]
+
+  # Optional: Add scopes using has_scope (if using Ransack or similar)
+  # Uncomment these lines if you have corresponding scopes in your <%= class_name %> model:
+  # has_scope :by_status
+  # has_scope :search, using: :name_cont
+  # has_scope :created_after, type: :date
+
+  # All CRUD methods (index, show, create, update, destroy) are inherited from <%= api_controller_class_name %>
+  # The inherited methods provide:
+  # - Automatic pagination via Pagy
+  # - Facet-based JSON rendering
+  # - Strong parameter filtering
+  # - Error handling
+  # - Resource finding and creation
+
+   # Callbacks can be added to run code before or after the default CRUD actions
+  # Use standard Rails before_action and after_action callbacks:
+  #
+  # before_action :your_method_name, only: [:create, :update]
+  # after_action :another_method, only: :destroy
+  #
+  # Example callbacks:
+  #
+  # before_action :set_defaults, only: :create
+  # before_action :check_ownership, only: [:update, :destroy] 
+  # after_action :notify_users, only: [:create, :update, :destroy]
+  #
+  # def set_defaults
+  #   # Set default values before creation
+  # end
+  #
+  # def check_ownership
+  #   # Verify resource ownership
+  # end
+  #
+  # def notify_users
+  #   # Send notifications after changes
+  # end
+
+  # Override any inherited methods here as a last result if you need custom behavior that can't be handled by callbacks:
+  #
+  # def index
+  #   # Custom index logic (e.g., additional filtering)
+  #   @pagy, resources = pagy(apply_scopes(resource_class.includes(:association)))
+  #   render json: { 
+  #     data: resources.map { |resource| resource_json(resource) },
+  #     pagination: pagy_metadata(@pagy)
+  #   }
+  # end
+  #
+  # def create
+  #   # Custom creation logic (e.g., set current user)
+  #   @resource = resource_class.new(resource_params)
+  #   @resource.user = current_user # Example: set current user
+  #   
+  #   if @resource.save
+  #     render json: { data: resource_json(@resource) }, status: :created
+  #   else
+  #     render json: { errors: @resource.errors }, status: :unprocessable_entity
+  #   end
+  # end
+  #
+  # def show
+  #   # Custom show logic (e.g., check permissions)
+  #   authorize! :read, @resource # Example: authorization check
+  #   render json: { data: resource_json(@resource) }
+  # end
+end

data/lib/generators/propel_api/templates/scaffold/facet_model_template.rb.tt

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationRecord
+
+  # Validations
+<% unless options[:skip_tenancy] -%>
+  # Multi-tenancy: Organization is always required
+  validates :organization, presence: true
+  
+<% end -%>
+<% attributes.reject { |attr| attr.type == :references }.each do |attribute| -%>
+<% if attribute.required? -%>
+  validates :<%= attribute.name %>, presence: true
+<% end -%>
+<% case attribute.type -%>
+<% when :integer -%>
+  validates :<%= attribute.name %>, numericality: { only_integer: true }, allow_nil: <%= !attribute.required? %>
+<% when :decimal, :float -%>
+  validates :<%= attribute.name %>, numericality: true, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(email|email_address)\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: URI::MailTo::EMAIL_REGEXP }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(phone|phone_number)\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: /\A\+?[\d\s-\(\)]+\z/ }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(url|website|web_address)\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: URI::DEFAULT_PARSER.make_regexp(%w[http https]) }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\Alatitude\z/i) -%>
+  validates :<%= attribute.name %>, numericality: { greater_than_or_equal_to: -90, less_than_or_equal_to: 90 }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\Alongitude\z/i) -%>
+  validates :<%= attribute.name %>, numericality: { greater_than_or_equal_to: -180, less_than_or_equal_to: 180 }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(zip|postal)_code\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: /\A\d{5}(-\d{4})?\z/ }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(username)\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: /\A[a-zA-Z0-9_-]+\z/ }, length: { minimum: 3, maximum: 30 }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% if attribute.name.to_s.match?(/\A(ip_address)\z/i) -%>
+  validates :<%= attribute.name %>, format: { with: /\A((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\z/ }, allow_nil: <%= !attribute.required? %>
+<% end -%>
+<% end -%>
+
+# Associations
+<% unless options[:skip_tenancy] -%>
+  # Multi-tenancy: Always include organization (required) and agency (optional)
+  belongs_to :organization
+  belongs_to :agency, optional: true
+  
+<% end -%>
+<% if defined?(relationship_inferrer) && relationship_inferrer.should_generate_associations? -%>
+<% relationship_inferrer.belongs_to_relationships.each do |relationship| -%>
+<% # Skip organization and agency if tenancy is included (they're already added above) -%>
+<% unless !options[:skip_tenancy] && (relationship.include?('organization') || relationship.include?('agency')) -%>
+  <%= relationship %>
+<% end -%>
+<% end -%>
+<% else -%>
+<% attributes.select { |attr| attr.type == :references }.each do |attribute| -%>
+<% # Skip organization and agency if tenancy is included (they're already added above) -%>
+<% unless !options[:skip_tenancy] && (attribute.name == 'organization' || attribute.name == 'agency') -%>
+<% if attribute.name == 'organization' -%>
+  belongs_to :organization
+<% else -%>
+  belongs_to :<%= attribute.name %>, optional: true
+<% end -%>
+<% end -%>
+<% end -%>
+<% end -%>
+# Add additional associations here
+# has_many :comments, dependent: :destroy
+
+# Scopes (useful for has_scope in controllers)
+# scope :active, -> { where(active: true) }
+# scope :by_status, ->(status) { where(status: status) }
+# scope :created_after, ->(date) { where('created_at > ?', date) }
+
+# Instance methods
+# Add your custom methods here
+# def full_name
+#   "#{first_name} #{last_name}"
+# end
+
+# Facets
+json_facet :short, fields: [:id<% 
+  # Include common identifying/summary fields for short facet
+  short_attributes = attributes.select do |attr|
+    # Include common identifying fields
+    identifying_fields = %w[name title label slug username email status state active published visible enabled]
+    # Include simple types but exclude large content and timestamps
+    simple_types = [:string, :integer, :boolean, :decimal, :float]
+    # Exclude large content fields, timestamps, and security-sensitive fields
+    excluded_patterns = /\A(description|content|body|notes|comment|bio|about|summary|created_at|updated_at|deleted_at|password|digest|token|secret|key|salt|encrypted|confirmation|unlock|reset|api_key|access_token|refresh_token)\z/i
+    
+    # Always exclude if the field contains security-sensitive words
+    security_patterns = /(password|digest|token|secret|key|salt|encrypted|confirmation|unlock|reset|api_key)/i
+    
+    identifying_fields.include?(attr.name.to_s) || 
+    (simple_types.include?(attr.type) && 
+     attr.name.to_s !~ excluded_patterns && 
+     attr.name.to_s !~ security_patterns &&
+     attr.name.to_s.length < 20)
+  end
+  short_attributes.each do |attribute| -%>, :<%= attribute.name %><% end %>]
+json_facet :details, fields: [:id<% 
+  # Include most fields except timestamps, security-sensitive, and internal Rails fields for details facet
+  detail_attributes = attributes.reject do |attr|
+    # Exclude timestamps and internal fields
+    excluded_patterns = /\A(created_at|updated_at|deleted_at|password_digest|reset_password_token|confirmation_token|unlock_token)\z/i
+    # Always exclude security-sensitive fields
+    security_patterns = /(password|digest|token|secret|key|salt|encrypted|confirmation|unlock|reset|api_key|access_token|refresh_token)/i
+    # Exclude binary and large data types
+    excluded_types = [:binary]
+    
+    excluded_patterns.match?(attr.name.to_s) || 
+    security_patterns.match?(attr.name.to_s) ||
+    excluded_types.include?(attr.type)
+  end
+  detail_attributes.each do |attribute| -%>, :<%= attribute.name %><% end -%><% attributes.select { |attr| attr.type == :references }.each do |reference| -%>, :<%= reference.name %><% end -%><% unless options[:skip_tenancy] -%>, :organization, :agency<% end -%>]
+
+# Example of more complex json_facet configurations:
+#
+# # Include associated models
+# json_facet :author, include: [:user]
+# 
+# # Include multiple associations
+# json_facet :with_comments, include: [:user, :comments]
+# 
+# # Include nested associations with custom names
+# json_facet :detailed, include_as: { user: :author, comments: :replies }
+#
+# # Use methods for computed attributes
+# json_facet :computed, methods: [:full_name, :calculated_total]
+#
+# # Combine fields, methods and includes
+# json_facet :complete, :name, :email, methods: [:status], include: [:posts]
+
+end

data/lib/generators/propel_api/templates/scaffold/graphiti_controller_template.rb.tt

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class <%= controller_class_name_with_namespace %>Controller < <%= api_controller_class_name %>
+  # Specify the Graphiti resource class for this controller
+  self.resource = <%= class_name %>Resource
+
+  # All CRUD methods (index, show, create, update, destroy) are inherited from <%= api_controller_class_name %>
+  # The inherited methods provide:
+  # - JSON:API compliant responses
+  # - Automatic filtering, sorting, and pagination
+  # - Resource-based parameter handling
+  # - Error handling
+  # - Authentication
+
+  # Callbacks can be added to run code before or after the default CRUD actions
+  # Use standard Rails before_action and after_action callbacks:
+  #
+  # before_action :your_method_name, only: [:create, :update]
+  # after_action :another_method, only: :destroy
+  #
+  # Example callbacks:
+  #
+  # before_action :set_defaults, only: :create
+  # before_action :check_ownership, only: [:update, :destroy] 
+  # after_action :notify_users, only: [:create, :update, :destroy]
+  #
+  # def set_defaults
+  #   # Set default values before creation
+  # end
+  #
+  # def check_ownership
+  #   # Verify resource ownership
+  # end
+  #
+  # def notify_users
+  #   # Send notifications after changes
+  # end
+
+  # Override any inherited methods here as a last resort if you need custom behavior that can't be handled by callbacks:
+  #
+  # def index
+  #   # Custom index logic (e.g., additional filtering)
+  #   resources = resource.all(params)
+  #   respond_with(resources)
+  # end
+  #
+  # def create
+  #   # Custom creation logic (e.g., set current user)
+  #   resource_instance = resource.build(params)
+  #   resource_instance.data.user = current_user # Example: set current user
+  #   
+  #   if resource_instance.save
+  #     respond_with(resource_instance, status: :created)
+  #   else
+  #     respond_with(resource_instance.errors, status: :unprocessable_entity)
+  #   end
+  # end
+  #
+  # def show
+  #   # Custom show logic (e.g., check permissions)
+  #   resource_instance = resource.find(params)
+  #   authorize! :read, resource_instance.data # Example: authorization check
+  #   respond_with(resource_instance)
+  # end
+
+  private
+
+  # Alternative: Override the resource method instead of using self.resource
+  # def resource
+  #   <%= class_name %>Resource
+  # end
+
+  # Add any private helper methods specific to <%= class_name.downcase %> here:
+  #
+  # def authorize_<%= singular_table_name %>_access
+  #   # Custom authorization logic
+  # end
+  #
+  # def additional_<%= singular_table_name %>_setup
+  #   # Custom setup logic
+  # end
+end 

data/lib/generators/propel_api/templates/scaffold/graphiti_model_template.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationRecord
+  # Graphiti uses resource classes for serialization, so no facets needed here
+  # Serialization is handled by the Graphiti resource class in app/resources/
+
+  # Validations
+  # Add your model validations here
+  # validates :name, presence: true
+  # validates :email, presence: true, uniqueness: true
+
+  # Associations
+  # Add your model associations here
+  # belongs_to :user
+  # has_many :comments, dependent: :destroy
+
+  # Scopes (useful for Graphiti resource filtering)
+  # scope :active, -> { where(active: true) }
+  # scope :by_status, ->(status) { where(status: status) }
+  # scope :created_after, ->(date) { where('created_at > ?', date) }
+
+  # Instance methods
+  # Add your custom methods here
+  # def full_name
+  #   "#{first_name} #{last_name}"
+  # end
+
+  private
+
+  # Private methods
+  # Add any private helper methods here
+end