operandi 5.0.0

data/docs/pundit-authorization.md

@@ -0,0 +1,320 @@
+# Pundit Authorization
+
+[Pundit](https://github.com/varvet/pundit) is a simple, flexible authorization library for Ruby on Rails. This recipe shows how to integrate Pundit authorization into your Operandi.
+
+## Why Use Pundit with Services?
+
+- **Centralized authorization**: Keep authorization logic in policy classes
+- **Consistent patterns**: Same authorization approach across controllers and services
+- **Testable**: Policies are easy to unit test
+- **Reusable**: Services can be called from controllers, jobs, or other services with consistent authorization
+
+## Basic Setup
+
+### 1. Create an Authorization Concern
+
+```ruby
+# app/services/concerns/authorize_user.rb
+module AuthorizeUser
+  extend ActiveSupport::Concern
+
+  included do
+    arg :current_user, type: User, optional: true, context: true
+  end
+
+  # Authorize an action on a record or class
+  def auth(record, action)
+    policy = policy(record)
+    
+    unless policy.public_send(action)
+      errors.add(:authorization, "You are not authorized to perform this action")
+    end
+  end
+  alias_method :authorize!, :auth
+
+  # Get permitted attributes for an action
+  def permitted_attributes(record, action = nil)
+    policy = policy(record)
+    
+    method_name = if action
+      "permitted_attributes_for_#{action}"
+    else
+      "permitted_attributes"
+    end
+
+    if policy.respond_to?(method_name)
+      attributes = policy.public_send(method_name)
+      params.require(param_key(record)).permit(*attributes)
+    else
+      raise Pundit::NotDefinedError, "#{method_name} not defined in #{policy.class}"
+    end
+  end
+
+  private
+
+  def policy(record)
+    Pundit.policy!(current_user, record)
+  end
+
+  def param_key(record)
+    if record.is_a?(Class)
+      record.model_name.param_key
+    else
+      record.model_name.param_key
+    end
+  end
+end
+```
+
+### 2. Include in ApplicationService
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Operandi::Base
+  include AuthorizeUser
+end
+```
+
+## Usage Examples
+
+### Authorizing Actions
+
+```ruby
+class Post::Update < ApplicationService
+  arg :post, type: Post
+  arg :attributes, type: Hash
+
+  step :authorize
+  step :update_post
+
+  private
+
+  def authorize
+    auth(post, :update?)
+  end
+
+  def update_post
+    post.update!(attributes)
+  end
+end
+```
+
+### Authorizing on a Class (for Create actions)
+
+```ruby
+class Post::Create < ApplicationService
+  arg :attributes, type: Hash
+
+  step :authorize
+  step :create_post
+
+  output :post
+
+  private
+
+  def authorize
+    auth(Post, :create?)
+  end
+
+  def create_post
+    self.post = Post.create!(attributes)
+  end
+end
+```
+
+### Using Permitted Attributes
+
+```ruby
+class Post::Create < ApplicationService
+  step :authorize
+  step :create_post
+
+  output :post
+
+  private
+
+  def authorize
+    auth(Post, :create?)
+  end
+
+  def create_post
+    self.post = Post.create!(permitted_attributes(Post, :create))
+  end
+end
+```
+
+## Policy Example
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
+  def create?
+    !user.nil?
+  end
+
+  def update?
+    !user.nil? && (record.author == user || user.admin?)
+  end
+
+  def destroy?
+    !user.nil? && (record.author == user || user.admin?)
+  end
+
+  def permitted_attributes_for_create
+    [:title, :body, :category_id]
+  end
+
+  def permitted_attributes_for_update
+    attributes = [:title, :body]
+    attributes << :category_id if user.admin?
+    attributes
+  end
+end
+```
+
+## Integration with CRUD Services
+
+Combine Pundit with the [CRUD recipe](crud.md) for powerful, authorized services:
+
+```ruby
+# app/services/create_record_service.rb
+class CreateRecordService < ApplicationService
+  arg :record_class, type: Class
+  arg :attributes, type: Hash, default: {}
+
+  step :authorize
+  step :create_record
+
+  output :record
+
+  private
+
+  def authorize
+    auth(record_class, :create?)
+  end
+
+  def create_record
+    attrs = permitted_attributes(record_class, :create)
+              .to_h
+              .merge(attributes)
+    
+    self.record = record_class.create!(attrs)
+  rescue ActiveRecord::RecordInvalid => e
+    errors.copy_from(e.record)
+  end
+end
+```
+
+## Handling Authorization Failures
+
+### Option 1: Collect as Errors (Default)
+
+```ruby
+def authorize
+  auth(record, :update?)
+  # If unauthorized, an error is added and subsequent steps are skipped
+end
+```
+
+### Option 2: Raise Exceptions
+
+```ruby
+def authorize
+  unless policy(record).update?
+    raise Pundit::NotAuthorizedError, "not authorized to update this record"
+  end
+end
+```
+
+### Option 3: Custom Error Handling
+
+```ruby
+def authorize
+  return if policy(record).update?
+  
+  errors.add(:base, I18n.t("pundit.not_authorized"))
+end
+```
+
+## Testing Services with Authorization
+
+```ruby
+RSpec.describe Post::Update do
+  let(:author) { create(:user) }
+  let(:other_user) { create(:user) }
+  let(:post) { create(:post, author: author) }
+
+  context "when user is the author" do
+    it "updates the post" do
+      service = described_class.run(
+        current_user: author,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_successful
+      expect(post.reload.title).to eq("New Title")
+    end
+  end
+
+  context "when user is not the author" do
+    it "returns authorization error" do
+      service = described_class.run(
+        current_user: other_user,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_failed
+      expect(service.errors[:authorization]).to be_present
+    end
+  end
+
+  context "when no user is provided" do
+    it "returns authorization error" do
+      service = described_class.run(
+        current_user: nil,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_failed
+    end
+  end
+end
+```
+
+## Skipping Authorization
+
+For system-level operations or background jobs where authorization isn't needed:
+
+```ruby
+class Post::SystemUpdate < UpdateRecordService
+  # Remove the authorize step for system operations
+  remove_step :authorize
+end
+```
+
+Or create a "system" flag:
+
+```ruby
+class ApplicationService < Operandi::Base
+  arg :system, type: [TrueClass, FalseClass], default: false, context: true
+end
+
+class Post::Update < ApplicationService
+  step :authorize, unless: :system?
+  step :update_post
+  
+  # ...
+end
+
+# Usage in background job
+Post::Update.run(post: post, attributes: attrs, system: true)
+```
+
+## What's Next?
+
+Return to the recipes overview:
+
+[Back to Recipes](recipes.md)

data/docs/quickstart.md

@@ -0,0 +1,133 @@
+# Quickstart
+
+Operandi are framework-agnostic and can be used in any Ruby project.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "operandi", "~> 3.0"
+```
+
+Or you can install it yourself by running:
+
+```bash
+bundle add operandi --version "~> 3.0"
+```
+
+## Create `ApplicationService`
+
+{% hint style="info" %}
+This step is optional but recommended. Creating a base class for your services can help organize your code. This base class will act as the parent for all your services, where you can include common logic such as helpers, logging, error handling, etc.
+{% endhint %}
+
+### For Rails Applications
+
+If you're using Rails, you can use the install generator to set up Operandi automatically:
+
+```bash
+bin/rails generate operandi:install
+```
+
+This will create the `ApplicationService` base class, an initializer, and a spec file (if RSpec is detected). See [Rails Generators](generators.md) for more details.
+
+### For Non-Rails Applications
+
+First, create a folder for your services. The path will depend on the framework you are using. For Rails, you can create a folder in `app/services`.
+
+```bash
+mkdir app/services
+```
+
+Next, create your base class. You can name it as you wish, but we recommend `ApplicationService`.
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Operandi::Base
+  # Add common arguments, callbacks, or helpers shared across all services.
+  #
+  # Example: Add a context argument for the current user
+  # arg :current_user, type: User, optional: true, context: true
+end
+```
+
+## Create Your First Service
+
+Now let's create our first service. We'll make a simple service that returns a greeting message.
+
+{% hint style="info" %}
+**Rails users:** You can use the service generator to create services quickly:
+```bash
+bin/rails generate operandi:service GreetService --args=name --steps=greet --outputs=greeted
+```
+See [Rails Generators](generators.md) for more information.
+{% endhint %}
+
+```ruby
+# app/services/greet_service.rb
+class GreetService < ApplicationService
+  # Arguments
+  arg :name, type: String
+
+  # Steps
+  step :greet
+
+  # Outputs
+  output :greeted, type: [TrueClass, FalseClass], default: false
+
+  private
+
+  def greet
+    puts "Hello, #{name}!"
+    self.greeted = true
+  end
+end
+```
+
+## Run the Service
+
+Now you can run your service from anywhere in your application.
+
+```ruby
+service = GreetService.run(name: "John")
+service.greeted # => true
+```
+
+### Check for Success or Failure
+
+```ruby
+service = GreetService.run(name: "John")
+
+if service.success?
+  puts "Greeting sent!"
+  puts service.greeted
+else
+  puts "Failed: #{service.errors.to_h}"
+end
+```
+
+### Raise on Error with `run!`
+
+Use `run!` when you want errors to raise exceptions instead of being collected:
+
+```ruby
+# This will raise Operandi::RuntimeError if any errors are added
+service = GreetService.run!(name: "John")
+```
+
+This is equivalent to:
+
+```ruby
+service = GreetService.run({ name: "John" }, { raise_on_error: true })
+```
+
+{% hint style="info" %}
+Looks easy, right? But this is just the beginning. Operandi can do much more 🚀
+{% endhint %}
+
+## What's Next?
+
+Learn how to configure Operandi for your application:
+
+[Next: Configuration](configuration.md)

data/docs/recipes.md

@@ -0,0 +1,14 @@
+# Recipes
+
+This section contains practical recipes for common patterns when using Operandi.
+
+- [CRUD](crud.md) - Implementing top-level services for CRUD operations
+- [Service Rendering](service-rendering.md) - Easy way to render service results and errors
+- [Pundit Authorization](pundit-authorization.md) - Integrating Pundit authorization with Operandi
+
+## Getting Started
+
+These recipes build upon each other. We recommend starting with CRUD services, then adding service rendering for cleaner controllers, and finally integrating Pundit for authorization.
+
+[Start with CRUD](crud.md)
+