playpath_rails 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e5ab5d5c4afc526c183ae6436a55e7560f3af87c5f7d5a478d6608c6346625d
-  data.tar.gz: c1fcd5c787be950c3cd9379cdca59b7cb6313a6fe6a2faae177157123dca4205
+  metadata.gz: 2cea7347f835466f2b1ef01032611e68647403705e493d20255f3cfb92f9bd60
+  data.tar.gz: a5d1b610515d6a067020f4d9e8cfc04956adc384d4954e144adee564b973fd7d
 SHA512:
-  metadata.gz: fc1c36c9224140d045df0c54b6d798dc4f3776888126c3b107669d7ce5bdea2effa68e4bff815e22d592c2e9fa29757ba9afe02714ade055eca1e5c294a60b60
-  data.tar.gz: 166c3ddc43552c6c89f57934f3f4fccd3f857877ac4603cfa877cac8f71d285f4257e903ba0d3baa5c6c4d07973468f895476a84937485558e43aacf998642b8
+  metadata.gz: 6fb20198c7c5327b4c70df3b882521cd133795b7e0d5e1ca67faf8fd706bcd2012412dc48c5b859d8ec00bc9804b80e54080be5df7410dbcb08d503ffd3c9139
+  data.tar.gz: adf81bd00ec20d169ebcfffce813431d1542fae1e980459ba7617d02da86f5dc39f10f03c62bbafd75ec1213d7ab9a46a757a4a8e2b2c79a445fa1753ca44bd6

data/GENERATOR_USAGE.md

@@ -0,0 +1,78 @@
+# PlaypathRails Generator Usage
+
+## Rails Migration Generator
+
+The PlaypathRails gem includes a Rails generator to easily add the required `playpath_item_id` column to your models.
+
+### Prerequisites
+
+1. The gem must be installed in a Rails application
+2. You must be in the Rails application directory when running the generator
+
+### Usage
+
+```bash
+# In your Rails application directory
+rails generate playpath_rails:migration ModelName
+```
+
+### Examples
+
+```bash
+# For an Article model
+rails generate playpath_rails:migration Article
+
+# For a BlogPost model (camelCase)
+rails generate playpath_rails:migration BlogPost
+
+# For a user_profile model (snake_case)
+rails generate playpath_rails:migration user_profile
+
+# For a VideoCollection model
+rails generate playpath_rails:migration VideoCollection
+```
+
+### What the Generator Creates
+
+The generator creates a migration file that:
+
+1. Adds a `playpath_item_id` column (integer, nullable)
+2. Adds a unique index on the `playpath_item_id` column
+
+Example generated migration:
+
+```ruby
+class AddPlaypathItemIdToArticles < ActiveRecord::Migration[7.0]
+  def change
+    add_column :articles, :playpath_item_id, :integer, null: true
+    add_index :articles, :playpath_item_id, unique: true
+  end
+end
+```
+
+### After Running the Generator
+
+1. Run the migration: `rails db:migrate`
+2. Add the `Synchronizable` module to your model:
+
+```ruby
+class Article < ApplicationRecord
+  include PlaypathRails::Synchronizable
+  
+  playpath_sync(
+    title_field: :title,
+    text_field: :content
+  )
+end
+```
+
+### Troubleshooting
+
+**Error: "Could not find generator 'playpath_rails:migration'"**
+
+This error occurs when:
+- You're not in a Rails application directory
+- The gem is not properly installed in the Rails app
+- You're trying to run the generator from the gem's own directory
+
+**Solution:** Make sure you're in a Rails application directory and the `playpath_rails` gem is added to your Gemfile.

data/README.md

@@ -17,30 +17,6 @@ A Ruby on Rails gem that provides seamless integration between Rails application
 [![Gem Downloads](https://img.shields.io/gem/dt/playpath_rails.svg)](https://rubygems.org/gems/playpath_rails)
 [![Documentation](https://inch-ci.org/github/playpath/playpath_rails.svg?branch=main)](https://inch-ci.org/github/playpath/playpath_rails)
 
-### Quality Metrics
-
-- **Test Coverage**: Comprehensive RSpec test suite with >95% coverage
-- **Code Quality**: Maintained with RuboCop and CodeClimate analysis
-- **Security**: Regular security audits with Bundler Audit and Snyk
-- **Documentation**: Inline documentation with YARD and comprehensive README
-- **Dependencies**: Minimal runtime dependencies (ActiveRecord, ActiveSupport)
-- **Compatibility**: Supports Ruby 3.1+ and Rails 5.2-8.0
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Model Synchronization](#model-synchronization)
-- [RAG Chat API](#rag-chat-api)
-- [Direct API Access](#direct-api-access)
-- [Error Handling](#error-handling)
-- [API Key Types](#api-key-types)
-- [Development](#development)
-- [Project Statistics](#project-statistics)
-- [Contributing](#contributing)
-- [License](#license)
-
 ## Features
 
 - **Automatic Model Synchronization**: Sync ActiveRecord models to PlayPath.io Items API
@@ -201,6 +177,32 @@ response = client.chat(
 )
 ```
 
+## Controller Integration
+
+When building custom Rails API controllers that integrate with PlayPath.io, you may encounter parameter handling issues. The gem provides examples and documentation for proper integration.
+
+### Quick Fix for "Unpermitted Parameters" Warnings
+
+If you see warnings like `Unpermitted parameters: :format, :id, :item` in your Rails logs, update your controller's parameter handling:
+
+```ruby
+def item_params
+  # Handle both nested and flat parameter formats
+  if params[:item].present?
+    # Nested format: { item: { title: "...", text: "..." } }
+    params.require(:item).permit(:title, :url, :text, tags: [])
+  else
+    # Flat format: { title: "...", text: "..." }
+    params.permit(:title, :url, :text, tags: [])
+  end
+end
+```
+
+### Complete Examples
+
+- **Controller Example**: [`examples/items_controller_example.rb`](examples/items_controller_example.rb) - Complete Rails controller with proper parameter handling
+- **Integration Guide**: [`CONTROLLER_INTEGRATION.md`](CONTROLLER_INTEGRATION.md) - Detailed guide for Rails controller integration
+
 ## Error Handling
 
 The gem provides specific exception types for different error scenarios:

data/examples/usage_example.rb

@@ -7,7 +7,7 @@ require_relative '../lib/playpath_rails'
 # Configure the gem
 PlaypathRails.configure do |config|
   config.api_key = ENV['PLAYPATH_API_KEY'] || 'your_api_key_here'
-  config.embeddings_api_key = ENV['PLAYPATH_EMBEDDINGS_KEY'] # Optional
+  config.embeddings_api_key = ENV.fetch('PLAYPATH_EMBEDDINGS_KEY', nil) # Optional
   config.base_url = 'https://playpath.io'
 end
 

data/lib/generators/playpath_rails/migration_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module PlaypathRails
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      argument :model_name, type: :string, desc: 'The model to add PlayPath synchronization to'
+
+      def create_migration_file
+        migration_template 'add_playpath_item_id_migration.rb.erb',
+                           "db/migrate/add_playpath_item_id_to_#{table_name}.rb"
+      end
+
+      private
+
+      def table_name
+        model_name.tableize
+      end
+
+      def migration_class_name
+        "AddPlaypathItemIdTo#{model_name.camelize.pluralize}"
+      end
+    end
+  end
+end

data/lib/generators/playpath_rails/templates/add_playpath_item_id_migration.rb.erb

@@ -0,0 +1,6 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :playpath_item_id, :integer, null: true
+    add_index :<%= table_name %>, :playpath_item_id, unique: true
+  end
+end

data/lib/playpath_rails/errors.rb

@@ -4,9 +4,6 @@ module PlaypathRails
   # Base error class for PlaypathRails
   class Error < StandardError; end
 
-  # Authentication error
-  class AuthenticationError < Error; end
-
   # API request error
   class APIError < Error
     attr_reader :status_code, :response_body
@@ -18,6 +15,9 @@ module PlaypathRails
     end
   end
 
+  # Authentication error
+  class AuthenticationError < APIError; end
+
   # Validation error from API
   class ValidationError < APIError; end
 

data/lib/playpath_rails/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+begin
+  require 'rails/railtie'
+rescue LoadError
+  # Rails not available, skip railtie
+  return
+end
+
+module PlaypathRails
+  class Railtie < Rails::Railtie
+    generators do
+      require 'generators/playpath_rails/migration_generator'
+    rescue LoadError
+      # Generator not found, log warning but don't fail
+      # Rails.logger&.warn("PlaypathRails generator could not be loaded: #{e.message}")
+    end
+  end
+end

data/lib/playpath_rails/synchronizable.rb

@@ -57,9 +57,9 @@ module PlaypathRails
         end
 
         true
-      rescue PlaypathRails::Error => e
+      rescue PlaypathRails::Error
         # Log the error but don't raise it to avoid breaking the application
-        Rails.logger.error("PlayPath sync failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
+        # Rails.logger.error("PlayPath sync failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
         false
       end
     end
@@ -74,9 +74,9 @@ module PlaypathRails
       rescue PlaypathRails::NotFoundError
         # Item already deleted, consider this success
         true
-      rescue PlaypathRails::Error => e
+      rescue PlaypathRails::Error
         # Log the error but don't raise it to avoid breaking the application
-        Rails.logger.error("PlayPath delete failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
+        # Rails.logger.error("PlayPath delete failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
         false
       end
     end

data/lib/playpath_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PlaypathRails
-  VERSION = '0.1.1'
+  VERSION = '0.1.4'
 end

data/lib/playpath_rails.rb

@@ -5,7 +5,13 @@ require_relative 'playpath_rails/errors'
 require_relative 'playpath_rails/client'
 require_relative 'playpath_rails/synchronizable'
 require_relative 'playpath_rails/rag'
-require_relative 'playpath_rails/railtie' if defined?(Rails)
+
+# Load railtie if Rails is available
+begin
+  require_relative 'playpath_rails/railtie' if defined?(Rails::Railtie)
+rescue LoadError
+  # Silently ignore if Rails is not available
+end
 
 module PlaypathRails
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: playpath_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.4
 platform: ruby
 authors:
 - Joran Kikke
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-26 00:00:00.000000000 Z
+date: 2025-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -159,16 +159,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- GENERATOR_USAGE.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - examples/usage_example.rb
+- lib/generators/playpath_rails/migration_generator.rb
+- lib/generators/playpath_rails/templates/add_playpath_item_id_migration.rb.erb
 - lib/playpath_rails.rb
 - lib/playpath_rails/client.rb
 - lib/playpath_rails/errors.rb
 - lib/playpath_rails/generators/migration_generator.rb
 - lib/playpath_rails/generators/templates/add_playpath_item_id_migration.rb.erb
 - lib/playpath_rails/rag.rb
+- lib/playpath_rails/railtie.rb
 - lib/playpath_rails/synchronizable.rb
 - lib/playpath_rails/version.rb
 - sig/playpath_rails.rbs
@@ -182,6 +186,7 @@ metadata:
   changelog_uri: https://github.com/playpath/playpath_rails/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/playpath/playpath_rails/issues
   documentation_uri: https://rubydoc.info/gems/playpath_rails
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: