fosm-rails

class Invoice < ApplicationRecord
  include Fosm::Lifecycle

  lifecycle do
    state :draft,     initial: true
    state :sent
    state :paid,      terminal: true
    state :cancelled, terminal: true

    event :send_invoice, from: :draft,  to: :sent
    event :pay,          from: :sent,   to: :paid
    event :cancel,       from: [:draft, :sent], to: :cancelled

    guard :has_line_items, on: :send_invoice do |invoice|
      invoice.amount > 0
    end

    side_effect :notify_client, on: :send_invoice do |invoice, transition|
      InvoiceMailer.send_to_client(invoice).deliver_later
    end
  end
end

gem "fosm-rails"

Rails.application.routes.draw do
  mount Fosm::Engine => "/fosm"
  draw :fosm  # draws config/routes/fosm.rb (auto-created by generators)
end

Fosm.configure do |config|
  # The base controller the FOSM engine inherits from
  config.base_controller = "ApplicationController"

  # Who can access /fosm/admin — should be superadmin only
  config.admin_authorize = -> { redirect_to root_path unless current_user&.superadmin? }

  # How to authorize individual FOSM apps
  config.app_authorize = ->(_level) { authenticate_user! }

  # How to get the current user (for transition log actor tracking and RBAC)
  config.current_user_method = -> { current_user }

  # Layouts
  config.admin_layout = "admin"    # your admin layout
  config.app_layout   = "application"

  # Transition log write strategy:
  #   :sync     — INSERT inside the fire! transaction (strictest consistency, default)
  #   :async    — SolidQueue job after commit (non-blocking, recommended for production)
  #   :buffered — bulk INSERT every ~1s via background thread (highest throughput)
  config.transition_log_strategy = :async
end

lifecycle do
  state :draft,  initial: true   # starting state (exactly one allowed)
  state :active
  state :closed, terminal: true  # no transitions out of terminal states
end

event :activate,  from: :draft,             to: :active
event :close,     from: [:draft, :active],  to: :closed

guard :has_required_fields, on: :activate do |record|
  record.name.present? && record.amount.positive?
end

side_effect :send_notification, on: :activate do |record, transition|
  # transition contains: { from:, to:, event:, actor: }
  NotificationMailer.activated(record).deliver_later
end

lifecycle do
  state :draft, initial: true
  state :sent
  state :paid, terminal: true
  state :cancelled, terminal: true

  event :send_invoice, from: :draft,          to: :sent
  event :pay,          from: [:sent],         to: :paid
  event :cancel,       from: [:draft, :sent], to: :cancelled

  # ── Access control ────────────────────────────────────────────────
  access do
    # default: true → this role is auto-assigned to the record creator on create
    role :owner, default: true do
      can :crud                      # shorthand: create + read + update + delete
      can :send_invoice, :cancel     # lifecycle events this role may fire
    end

    role :approver do
      can :read                      # view the record
      can :pay                       # fire the :pay event (separation of duties)
    end

    role :viewer do
      can :read                      # read-only, no event access
    end
  end
end

# Type-level: Alice is an :approver for ALL Fosm::Invoice records
Fosm::RoleAssignment.create!(
  user_type:     "User",
  user_id:       alice.id.to_s,
  resource_type: "Fosm::Invoice",
  resource_id:   nil,           # nil = type-level
  role_name:     "approver"
)

# Record-level: Bob is an :owner for Invoice #42 only
Fosm::RoleAssignment.create!(
  user_type:     "User",
  user_id:       bob.id.to_s,
  resource_type: "Fosm::Invoice",
  resource_id:   "42",          # specific record
  role_name:     "owner"
)

class Fosm::InvoiceController < Fosm::ApplicationController
  before_action -> { fosm_authorize!(:read,   Fosm::Invoice) }, only: [:index, :show]
  before_action -> { fosm_authorize!(:create, Fosm::Invoice) }, only: [:new, :create]
  before_action -> { fosm_authorize!(:update, @record) },       only: [:edit, :update]
  before_action -> { fosm_authorize!(:delete, @record) },       only: [:destroy]
end

# Dynamic bang method (generated per event)
invoice.send_invoice!(actor: current_user)
invoice.pay!(actor: current_user)
invoice.cancel!(actor: current_user, metadata: { reason: "client request" })

# Or via the generic fire! method
invoice.fire!(:send_invoice, actor: current_user)

# Check before firing
invoice.can_send_invoice?     # => true/false
invoice.available_events      # => [:pay, :cancel]
invoice.draft?                # => false (state predicate)
invoice.sent?                 # => true

# app/agents/fosm/invoice_agent.rb
class Fosm::InvoiceAgent < Fosm::Agent
  model_class Fosm::Invoice
  default_model "anthropic/claude-sonnet-4-20250514"

  # Optional: add custom tools
  fosm_tool :find_overdue,
            description: "Find sent invoices past their due date",
            inputs: {} do
    Fosm::Invoice.where(state: "sent")
                 .where("due_date < ?", Date.today)
                 .map { |inv| { id: inv.id, due_date: inv.due_date.to_s } }
  end
end

# Use it
agent = Fosm::InvoiceAgent.build_agent
agent.run("Mark all sent invoices older than 30 days as overdue")

# Or use a different model
agent = Fosm::InvoiceAgent.build_agent(model: "openai/gpt-4o")
agent.run("Pay invoice #42 if it's in the correct state")

Fosm::WebhookSubscription.create!(
  model_class_name: "Fosm::Invoice",
  event_name: "send_invoice",
  url: "https://your-app.com/webhooks/fosm",
  secret_token: "your_signing_secret",
  active: true
)

Fosm::TransitionLog.for_record("Fosm::Invoice", 42).recent
# => [{ event: "send_invoice", from: "draft", to: "sent", actor: "user@example.com", at: "..." }]

Fosm::TransitionLog.for_app(Fosm::Invoice).by_event("pay").count
# => 17