jpie 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e1d1634f188bca4057e3550479af557bd00ba0d262c919ba221aa99997490e
-  data.tar.gz: 89db580da555f310a1b840daad204e2315fcb8b7828278b328271412d3bc321d
+  metadata.gz: 8d3cbfd72c12a023879f10c3314c321bf0210c861cffd838dc860d0497b53ae5
+  data.tar.gz: c8caf96a60fe557f7f07ce74e9cb725370b2d410856e33c2138f0bef7f1ba141
 SHA512:
-  metadata.gz: d2ced2be2db661db82e08200be2e5df033c072dcbf249565719336d3b08532d2cb01c4bbcec78cfb5e14fbbbadddb0c127292b70a9b970da3ecc20891bc8c8ab
-  data.tar.gz: 5d1ac4453eb74ba6a8ea04036f00065e26a54c2ff85a603525dd90106bd4f82a839ed3985083c5ff60d087b6bb1239c7a618a7a024e7e3fa1955c82d863aefa8
+  metadata.gz: dd2a288d7526fd45c3f2a30881019656a0772942d83f208e9a031d976223a8497ea29f00295d37d2c045805dae791a79f2d6d6be5c1835007dfd9ba1b6b8b4c2
+  data.tar.gz: 99a5f5e5fb484a394ce36c6ac9f5635c2f06c820dc6c41f16d89903e7135fde2b1e32d6a1a7df5277ee3ee3f248b15651a1353fb83315e96c9525a47b8638221

data/.cursor/rules/dependencies.mdc

@@ -0,0 +1,19 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Dependency Management
+
+## Requirements
+- Keep dependencies minimal and justified
+- Document new dependencies in README.md
+- Keep development dependencies in Gemfile
+- Ensure compatibility with Ruby 3.4+
+- Only support Rails 8+ features
+- Use modern gem versions
+
+## Compatibility Requirements
+- Maintain Ruby 3.4+ compatibility
+- Support Rails 8+ integration
+- Follow JSON:API specification strictly

data/.cursor/rules/examples.mdc

@@ -0,0 +1,16 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Example Guidelines
+
+- Examples must only include required code
+- Examples must not include any unrelated or superfluous code
+- Examples must be a single markdown file
+- Examples must use the `http` code blocks for examples
+- Examples must only include the minimum number of examples
+- Examples must never include migrations
+- Examples must not include a features section or similar
+- Examples must include an introduction to the example
+- Examples live in /examples/*.md

data/.cursor/rules/git.mdc

@@ -0,0 +1,14 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Git Commit Guidelines
+
+- Write clear, descriptive commit messages
+- Keep commits focused and atomic
+- Run and pass tests before committing
+- Update documentation in the same commit as code changes
+- Ignore spec/examples.txt and other files listed in .gitignore
+- Include Ruby/Rails version requirements in relevant commits
+- Update tests in the same commit as code changes

data/.cursor/rules/project_structure.mdc

@@ -0,0 +1,30 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Project Information
+- Project Name: jpie
+- Description: Ruby gem for JSON:API implementation
+
+# Project Structure
+
+## Core Structure
+- Keep core functionality in lib/jpie/
+- Place tests in spec/jpie/
+- Use proper namespacing (JPie module)
+- Follow Ruby gem best practices
+
+## Protected Files
+- Do not update spec/jpie/database.rb unless absolutely necessary
+- Do not update spec/jpie/resources.rb unless absolutely necessary
+
+## Documentation
+- Keep README.md up to date with installation and usage instructions
+- Include example usage in documentation
+
+## Development Process
+- Always read the .aiconfig file
+- Always implement code slowly and methodically
+- Always test as you go
+- Always make sure rubocop passes

data/.cursor/rules/security.mdc

@@ -0,0 +1,14 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Security Guidelines
+
+- Never commit sensitive data or credentials
+- Use environment variables for configuration
+- Follow secure coding practices
+- Keep dependencies up to date
+- Follow Rails 8+ security best practices
+- Use Ruby 3.4+ security features
+- Implement proper input validation

data/.cursor/rules/style.mdc

@@ -0,0 +1,15 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Style Guidelines
+
+## Ruby Style
+- Follow Ruby style guide and RuboCop rules defined in .rubocop.yml
+- Prefer rubocop autocorrect 
+- Always pass rubocop before committing to git
+- Use `{data:}` rather than `{data: data}`
+- Only use code comments when absolutely necessary
+- Keep any code comments short and concise
+- Don't update .rubocop.yml unless absolutely necessary

data/.cursor/rules/testing.mdc

@@ -0,0 +1,16 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Testing Guidelines
+
+- Write RSpec tests for all new features
+- Maintain test coverage for all public methods
+- Use meaningful test descriptions
+- Follow the existing test structure in spec/
+- Test both success and error cases
+- Use modern RSpec features and syntax
+- Don't reduce test coverage (line, file, branch, or other)
+- Only care about coverage reduction when running all specs
+- Do not add any functionality for new features to existing tests unless absolutely necessary

data/examples/relationships.md

@@ -0,0 +1,114 @@
+# JSON:API Relationship Management
+
+This example demonstrates how to manage relationships using JPie's JSON:API compliant relationship endpoints.
+
+## Setup
+
+Define your resources with relationships:
+
+```ruby
+# app/resources/user_resource.rb
+class UserResource < JPie::Resource
+  model User
+  attributes :name, :email
+  has_many :posts
+end
+
+# app/resources/post_resource.rb  
+class PostResource < JPie::Resource
+  model Post
+  attributes :title, :content
+  has_one :author, resource: 'UserResource'
+end
+
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include JPie::Controller
+end
+```
+
+Configure routes:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  jpie_resources :users
+  jpie_resources :posts
+end
+```
+
+## Relationship Operations
+
+### Get Relationship Linkage
+
+```http
+GET /users/1/relationships/posts
+
+Response:
+{
+  "data": [
+    { "type": "posts", "id": "1" },
+    { "type": "posts", "id": "3" }
+  ]
+}
+```
+
+### Replace Relationship
+
+```http
+PATCH /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "2" },
+    { "type": "posts", "id": "4" }
+  ]
+}
+```
+
+### Add to Relationship
+
+```http
+POST /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "5" }
+  ]
+}
+```
+
+### Remove from Relationship
+
+```http
+DELETE /users/1/relationships/posts
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "2" }
+  ]
+}
+```
+
+### Get Related Resources
+
+```http
+GET /users/1/posts
+
+Response:
+{
+  "data": [
+    {
+      "type": "posts",
+      "id": "1",
+      "attributes": {
+        "title": "First Post",
+        "content": "Hello world!"
+      }
+    }
+  ]
+}
+```

data/lib/jpie/controller/related_actions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module RelatedActions
+      extend ActiveSupport::Concern
+
+      # GET /resources/:id/:relationship_name
+      # Returns the related resources themselves (not just linkage)
+      def related_show
+        validate_relationship_exists
+        validate_include_params
+        resource = find_resource
+        related_resources = get_related_resources(resource)
+        render_jsonapi(related_resources)
+      end
+
+      private
+
+      def validate_relationship_exists
+        relationship_name = params[:relationship_name]
+        return unless relationship_name # Skip validation if no relationship_name param
+
+        return if resource_class._relationships.key?(relationship_name.to_sym)
+
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Relationship '#{relationship_name}' does not exist for #{resource_class.name}"
+        )
+      end
+
+      def find_resource
+        resource_class.scope(context).find(params[:id])
+      end
+
+      def relationship_name
+        @relationship_name ||= params[:relationship_name].to_sym
+      end
+
+      def get_related_resources(resource)
+        relationship_method = relationship_name
+        resource.send(relationship_method)
+      end
+    end
+  end
+end

data/lib/jpie/controller/relationship_actions.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require_relative 'relationship_validation'
+
+module JPie
+  module Controller
+    module RelationshipActions
+      extend ActiveSupport::Concern
+      include RelationshipValidation
+
+      # GET /resources/:id/relationships/:relationship_name
+      # Returns relationship linkage data
+      def relationship_show
+        validate_relationship_exists
+        resource = find_resource
+        relationship_data = get_relationship_data(resource)
+        render_relationship_data(relationship_data)
+      end
+
+      # PATCH /resources/:id/relationships/:relationship_name
+      # Updates relationship linkage (replaces all relationships)
+      def relationship_update
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+        relationship_data = parse_relationship_data
+        update_relationship_data(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      # POST /resources/:id/relationships/:relationship_name
+      # Adds to relationship linkage (for to-many relationships)
+      def relationship_create
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+
+        unless relationship_is_to_many?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'POST is only supported for to-many relationships'
+          )
+        end
+
+        relationship_data = parse_relationship_data
+
+        unless relationship_data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Adding to relationships requires an array of resource identifier objects'
+          )
+        end
+
+        add_to_relationship(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      # DELETE /resources/:id/relationships/:relationship_name
+      # Removes from relationship linkage (for to-many relationships)
+      def relationship_destroy
+        validate_relationship_exists
+        validate_relationship_update_request
+        resource = find_resource
+
+        unless relationship_is_to_many?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'DELETE is only supported for to-many relationships'
+          )
+        end
+
+        relationship_data = parse_relationship_data
+
+        unless relationship_data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Removing from relationships requires an array of resource identifier objects'
+          )
+        end
+
+        remove_from_relationship(resource, relationship_data)
+        render_relationship_data(get_relationship_data(resource))
+      end
+
+      private
+
+      def find_resource
+        resource_class.scope(context).find(params[:id])
+      end
+
+      def relationship_name
+        @relationship_name ||= params[:relationship_name].to_sym
+      end
+
+      def relationship_config
+        @relationship_config ||= resource_class._relationships[relationship_name]
+      end
+
+      def get_relationship_data(resource)
+        relationship_method = relationship_name
+        related_objects = resource.send(relationship_method)
+
+        if related_objects.respond_to?(:each)
+          # to-many relationship
+          related_objects.map { |obj| { type: infer_type(obj), id: obj.id.to_s } }
+        elsif related_objects
+          # to-one relationship
+          { type: infer_type(related_objects), id: related_objects.id.to_s }
+        end
+      end
+
+      def parse_relationship_data
+        body = request.body.read
+        request.body.rewind
+        parsed_body = JSON.parse(body)
+
+        unless parsed_body.key?('data')
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Request must include a "data" member'
+          )
+        end
+
+        parsed_body['data']
+      end
+
+      def update_relationship_data(resource, relationship_data)
+        if relationship_data.nil?
+          # Set relationship to null (only valid for to-one relationships)
+          unless relationship_is_to_many?
+            clear_relationship(resource)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Cannot set a to-many relationship to null'
+            )
+          end
+        elsif relationship_data.is_a?(Array)
+          # to-many relationship - replace all
+          if relationship_is_to_many?
+            replace_to_many_relationship(resource, relationship_data)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Invalid data type for to-one relationship'
+            )
+          end
+        elsif relationship_data.is_a?(Hash)
+          # to-one relationship - replace
+          unless relationship_is_to_many?
+            replace_to_one_relationship(resource, relationship_data)
+          else
+            raise JPie::Errors::BadRequestError.new(
+              detail: 'Invalid data type for to-many relationship'
+            )
+          end
+        else
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Relationship data must be null, an object, or an array of objects'
+          )
+        end
+      end
+
+      def add_to_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association = association_for_resource(resource)
+
+          related_objects.each do |related_object|
+            association << related_object unless association.include?(related_object)
+          end
+
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to add relationships: #{e.message}"
+          )
+        end
+      end
+
+      def remove_from_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association = association_for_resource(resource)
+
+          related_objects.each do |related_object|
+            association.delete(related_object)
+          end
+
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to remove relationships: #{e.message}"
+          )
+        end
+      end
+
+      def clear_relationship(resource)
+        association_name = association_name_for_relationship
+        resource.send("#{association_name}=", nil)
+        resource.save!
+      rescue ActiveRecord::RecordInvalid => e
+        raise JPie::Errors::ValidationError.new(
+          detail: "Failed to clear relationship: #{e.message}"
+        )
+      end
+
+      def replace_to_many_relationship(resource, relationship_data)
+        begin
+          related_objects = find_related_objects(relationship_data)
+          association_name = association_name_for_relationship
+          resource.send("#{association_name}=", related_objects)
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to replace relationships: #{e.message}"
+          )
+        end
+      end
+
+      def replace_to_one_relationship(resource, relationship_data)
+        begin
+          related_object = find_related_object(relationship_data)
+          association_name = association_name_for_relationship
+          resource.send("#{association_name}=", related_object)
+          resource.save!
+        rescue ActiveRecord::AssociationTypeMismatch => e
+          raise JPie::Errors::NotFoundError.new(
+            detail: "Related resource not found: Invalid resource type for relationship"
+          )
+        rescue ActiveRecord::RecordInvalid => e
+          raise JPie::Errors::ValidationError.new(
+            detail: "Failed to replace relationship: #{e.message}"
+          )
+        end
+      end
+
+      def find_related_objects(relationship_data)
+        relationship_data.map { |data| find_related_object(data) }
+      end
+
+      def find_related_object(resource_identifier)
+        validate_resource_identifier(resource_identifier)
+
+        type = resource_identifier['type']
+        id = resource_identifier['id']
+
+        related_model_class = infer_model_class_from_type(type)
+        related_model_class.find(id)
+      rescue ActiveRecord::RecordNotFound
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Related resource not found: #{type}##{id}"
+        )
+      end
+
+      def association_for_resource(resource)
+        association_name = association_name_for_relationship
+        resource.send(association_name)
+      end
+
+      def association_name_for_relationship
+        # For now, assume the relationship name matches the association name
+        # This could be made more sophisticated to handle custom association names
+        relationship_name
+      end
+
+      def infer_type(object)
+        # Convert model class name to JSON:API type
+        # e.g., "User" -> "users", "BlogPost" -> "blog-posts"
+        object.class.name.underscore.dasherize.pluralize
+      end
+
+      def infer_model_class_from_type(type)
+        # Convert JSON:API type back to model class
+        # e.g., "users" -> User, "blog-posts" -> BlogPost
+        class_name = type.singularize.underscore.camelize
+        class_name.constantize
+      end
+
+      def render_relationship_data(relationship_data)
+        response_data = { data: relationship_data }
+        render json: response_data, content_type: 'application/vnd.api+json'
+      end
+    end
+  end
+end

data/lib/jpie/controller/relationship_validation.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module JPie
+  module Controller
+    module RelationshipValidation
+      private
+
+      def validate_relationship_exists
+        relationship_name = params[:relationship_name]
+        return unless relationship_name # Skip validation if no relationship_name param
+
+        return if resource_class._relationships.key?(relationship_name.to_sym)
+
+        raise JPie::Errors::NotFoundError.new(
+          detail: "Relationship '#{relationship_name}' does not exist for #{resource_class.name}"
+        )
+      end
+
+      def validate_relationship_update_request
+        validate_content_type
+        validate_request_body
+        validate_relationship_type
+      end
+
+      def validate_content_type
+        # Only validate content type for write operations
+        return unless request.post? || request.patch? || request.put?
+
+        content_type = request.content_type
+        return if content_type&.include?('application/vnd.api+json')
+
+        raise JPie::Errors::InvalidJsonApiRequestError.new(
+          detail: 'Content-Type must be application/vnd.api+json for JSON:API requests'
+        )
+      end
+
+      def validate_request_body
+        body = request.body.read
+        request.body.rewind
+
+        raise JPie::Errors::BadRequestError.new(detail: 'Request body cannot be empty') if body.blank?
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise JPie::Errors::BadRequestError.new(detail: "Invalid JSON: #{e.message}")
+      end
+
+      def validate_resource_identifier(resource_identifier)
+        unless resource_identifier.is_a?(Hash) &&
+               resource_identifier.key?('type') &&
+               resource_identifier.key?('id')
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier objects must have "type" and "id" members'
+          )
+        end
+
+        type = resource_identifier['type']
+        id = resource_identifier['id']
+
+        unless type.is_a?(String) && id.is_a?(String)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier object members must be strings'
+          )
+        end
+
+        if type.empty? || id.empty?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Resource identifier object members cannot be empty strings'
+          )
+        end
+      end
+
+      def validate_relationship_type
+        validate_relationship_exists
+        data = parse_relationship_data
+
+        if relationship_is_to_many?
+          validate_to_many_relationship_data(data)
+        else
+          validate_to_one_relationship_data(data)
+        end
+      end
+
+      def validate_to_many_relationship_data(data)
+        if data.nil?
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'Cannot set a to-many relationship to null'
+          )
+        end
+
+        unless data.is_a?(Array)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'The value of data must be an array for to-many relationships'
+          )
+        end
+
+        data.each { |identifier| validate_resource_identifier(identifier) }
+      end
+
+      def validate_to_one_relationship_data(data)
+        unless data.nil? || data.is_a?(Hash)
+          raise JPie::Errors::BadRequestError.new(
+            detail: 'The value of data must be a single resource identifier object or null for to-one relationships'
+          )
+        end
+
+        validate_resource_identifier(data) if data
+      end
+
+      def relationship_is_to_many?
+        return false unless relationship_config
+
+        relationship_config[:type] == :has_many
+      end
+    end
+  end
+end

data/lib/jpie/controller.rb

@@ -6,6 +6,8 @@ require_relative 'controller/parameter_parsing'
 require_relative 'controller/rendering'
 require_relative 'controller/crud_actions'
 require_relative 'controller/json_api_validation'
+require_relative 'controller/relationship_actions'
+require_relative 'controller/related_actions'
 
 module JPie
   module Controller
@@ -16,5 +18,28 @@ module JPie
     include Rendering
     include CrudActions
     include JsonApiValidation
+    include RelationshipActions
+    include RelatedActions
+
+    # Relationship route actions
+    def show_relationship
+      relationship_show
+    end
+
+    def update_relationship
+      relationship_update
+    end
+
+    def create_relationship
+      relationship_create
+    end
+
+    def destroy_relationship
+      relationship_destroy
+    end
+
+    def show_related
+      related_show
+    end
   end
 end

data/lib/jpie/errors.rb

@@ -55,6 +55,12 @@ module JPie
       end
     end
 
+    class UnsupportedMediaTypeError < Error
+      def initialize(detail: 'Unsupported Media Type')
+        super(status: 415, title: 'Unsupported Media Type', detail:)
+      end
+    end
+
     class InternalServerError < Error
       def initialize(detail: 'Internal Server Error')
         super(status: 500, title: 'Internal Server Error', detail:)

data/lib/jpie/railtie.rb

@@ -29,6 +29,12 @@ module JPie
       end
     end
 
+    initializer 'jpie.routing' do
+      ActiveSupport.on_load(:action_dispatch) do
+        ActionDispatch::Routing::Mapper.include JPie::Routing
+      end
+    end
+
     generators do
       require 'jpie/generators/resource_generator'
     end

data/lib/jpie/resource/attributable.rb

@@ -59,13 +59,13 @@ module JPie
         def has_many(name, options = {})
           name = name.to_sym
           resource_class_name = options[:resource] || infer_resource_class_name(name)
-          relationship(name, { resource: resource_class_name }.merge(options))
+          relationship(name, { type: :has_many, resource: resource_class_name }.merge(options))
         end
 
         def has_one(name, options = {})
           name = name.to_sym
           resource_class_name = options[:resource] || infer_resource_class_name(name)
-          relationship(name, { resource: resource_class_name }.merge(options))
+          relationship(name, { type: :has_one, resource: resource_class_name }.merge(options))
         end
 
         private

data/lib/jpie/routing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module JPie
+  module Routing
+    # Add jpie_resources method to Rails routing DSL that creates JSON:API compliant routes
+    def jpie_resources(*resources)
+      options = resources.extract_options!
+      merged_options = build_merged_options(options)
+
+      # Create standard RESTful routes for the resource
+      resources(*resources, merged_options) do
+        yield if block_given?
+        add_jsonapi_relationship_routes(merged_options) if relationship_routes_allowed?(merged_options)
+      end
+    end
+
+    private
+
+    def build_merged_options(options)
+      default_options = {
+        defaults: { format: :json },
+        constraints: { format: :json }
+      }
+      default_options.merge(options)
+    end
+
+    def relationship_routes_allowed?(merged_options)
+      only_actions = merged_options[:only]
+      except_actions = merged_options[:except]
+
+      if only_actions
+        # If only specific actions are allowed, don't add relationship routes
+        # unless multiple member actions (show, update, destroy) are included
+        (only_actions & %i[show update destroy]).size >= 2
+      elsif except_actions
+        # If actions are excluded, only add if member actions aren't excluded
+        !except_actions.intersect?(%i[show update destroy])
+      else
+        true
+      end
+    end
+
+    def add_jsonapi_relationship_routes(_merged_options)
+      # These routes handle relationship management as per JSON:API spec
+      member do
+        # Routes for fetching and updating relationships
+        # Pattern: /resources/:id/relationships/:relationship_name
+        get 'relationships/*relationship_name', action: :show_relationship, as: :relationship
+        patch 'relationships/*relationship_name', action: :update_relationship
+        post 'relationships/*relationship_name', action: :create_relationship
+        delete 'relationships/*relationship_name', action: :destroy_relationship
+
+        # Routes for fetching related resources
+        # Pattern: /resources/:id/:relationship_name
+        get '*relationship_name', action: :show_related, as: :related
+      end
+    end
+  end
+end

data/lib/jpie/rspec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+module JPie
+  # RSpec matchers and helpers for testing JPie resources
+  module RSpec
+    # Configure RSpec with JPie helpers and matchers
+    def self.configure!
+      ::RSpec.configure do |config|
+        config.include JPie::RSpec::Matchers
+        config.include JPie::RSpec::Helpers
+      end
+    end
+
+    # Custom matchers for JPie resources
+    module Matchers
+      extend ::RSpec::Matchers::DSL
+
+      matcher :have_attribute do |attribute_name|
+        match do |actual|
+          actual.respond_to?(attribute_name) &&
+            actual.attributes.key?(attribute_name.to_s)
+        end
+
+        failure_message do |actual|
+          "expected #{actual.inspect} to have attribute '#{attribute_name}'"
+        end
+      end
+
+      matcher :have_relationship do |relationship_name|
+        match do |actual|
+          actual.respond_to?(relationship_name) &&
+            actual.relationships.key?(relationship_name.to_s)
+        end
+
+        failure_message do |actual|
+          "expected #{actual.inspect} to have relationship '#{relationship_name}'"
+        end
+      end
+    end
+
+    # Helper methods for testing JPie resources
+    module Helpers
+      # Build a JPie resource without saving it
+      def build_jpie_resource(type, attributes = {}, relationships = {})
+        JPie::Resource.new(
+          type: type,
+          attributes: attributes,
+          relationships: relationships
+        )
+      end
+
+      # Create a JPie resource and save it
+      def create_jpie_resource(type, attributes = {}, relationships = {})
+        resource = build_jpie_resource(type, attributes, relationships)
+        resource.save
+        resource
+      end
+
+      # Clean up test data after specs
+      def cleanup_jpie_resources(resources)
+        Array(resources).each do |resource|
+          resource.destroy if resource.persisted?
+        rescue StandardError => e
+          warn "Failed to cleanup resource #{resource.inspect}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/jpie/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JPie
-  VERSION = '0.4.2'
+  VERSION = '0.4.4'
 end

data/lib/jpie.rb

@@ -3,14 +3,19 @@
 require 'active_support'
 require 'active_support/core_ext'
 require 'jpie/version'
+require_relative 'jpie/resource'
+require_relative 'jpie/client'
+require_relative 'jpie/errors'
+
+# Load RSpec support if RSpec is defined
+require_relative 'jpie/rspec' if defined?(RSpec)
 
 module JPie
-  autoload :Resource, 'jpie/resource'
   autoload :Serializer, 'jpie/serializer'
   autoload :Deserializer, 'jpie/deserializer'
   autoload :Controller, 'jpie/controller'
   autoload :Configuration, 'jpie/configuration'
-  autoload :Errors, 'jpie/errors'
+  autoload :Routing, 'jpie/routing'
 
   class << self
     def configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Emil Kampp
@@ -169,7 +169,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".cursorrules"
+- ".cursor/rules/dependencies.mdc"
+- ".cursor/rules/examples.mdc"
+- ".cursor/rules/git.mdc"
+- ".cursor/rules/project_structure.mdc"
+- ".cursor/rules/security.mdc"
+- ".cursor/rules/style.mdc"
+- ".cursor/rules/testing.mdc"
 - ".overcommit.yml"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -179,6 +185,7 @@ files:
 - examples/basic_example.md
 - examples/including_related_resources.md
 - examples/pagination.md
+- examples/relationships.md
 - examples/resource_attribute_configuration.md
 - examples/resource_meta_configuration.md
 - examples/single_table_inheritance.md
@@ -192,6 +199,9 @@ files:
 - lib/jpie/controller/error_handling/handlers.rb
 - lib/jpie/controller/json_api_validation.rb
 - lib/jpie/controller/parameter_parsing.rb
+- lib/jpie/controller/related_actions.rb
+- lib/jpie/controller/relationship_actions.rb
+- lib/jpie/controller/relationship_validation.rb
 - lib/jpie/controller/rendering.rb
 - lib/jpie/deserializer.rb
 - lib/jpie/errors.rb
@@ -202,6 +212,8 @@ files:
 - lib/jpie/resource/attributable.rb
 - lib/jpie/resource/inferrable.rb
 - lib/jpie/resource/sortable.rb
+- lib/jpie/routing.rb
+- lib/jpie/rspec.rb
 - lib/jpie/serializer.rb
 - lib/jpie/version.rb
 homepage: https://github.com/emk-klaay/jpie

data/.cursorrules

@@ -1,81 +0,0 @@
-# AI Assistant Configuration
-# This file contains rules and guidelines for AI assistants working on the jpie project
-
-# Follow these code style guidelines
-- Follow Ruby style guide and RuboCop rules defined in .rubocop.yml
-- Prefer rubocop autocorrect 
-- Always pass rubocop before committing to git
-- Use `{data:}` rather than `{data: data}`
-- Only use code comments when abasolutely necessary
-- Keep any code comments short and concise
-- Don't update the .rubocop.yml unless it's absolutely necessarry
-
-# Documentation requirements
-- Keep README.md up to date with installation and usage instructions
-- Include example usage in documentation
-
-# Testing guidelines
-- Write RSpec tests for all new features
-- Maintain test coverage for all public methods
-- Use meaningful test descriptions
-- Follow the existing test structure in spec/
-- Test both success and error cases
-- Use modern RSpec features and syntax
-- Don't reduce test coverage (line, file, branch, or other)
-
-# Git commit guidelines
-- Write clear, descriptive commit messages
-- Keep commits focused and atomic
-- Run and pass tests before committing
-- Update documentation in the same commit as code changes
-- Ignore spec/examples.txt and other files listed in .gitignore
-- Include Ruby/Rails version requirements in relevant commits
-- Update tests in the same commit as code changes
-
-# Maintain the following project structure
-- Keep core functionality in lib/jpie/
-- Place tests in spec/jpie/
-- Use proper namespacing (JPie module)
-- Follow Ruby gem best practices
-- Do not update the spec/jpie/database.rb unless it's absolutely necessarry
-- Do not update the spec/jpie/resources.rb unless it's absolutely necessarry
-
-# Dependency management
-- Keep dependencies minimal and justified
-- Document new dependencies in README.md
-- Keep development dependencies in Gemfile
-- Ensure compatibility with Ruby 3.4+
-- Only support Rails 8+ features
-- Use modern gem versions
-
-# Security guidelines
-- Never commit sensitive data or credentials
-- Use environment variables for configuration
-- Follow secure coding practices
-- Keep dependencies up to date
-- Follow Rails 8+ security best practices
-- Use Ruby 3.4+ security features
-- Implement proper input validation
-
-# Compatibility requirements
-- Maintain Ruby 3.4+ compatibility
-- Support Rails 8+ integration
-- Follow JSON:API specification strictly
-
-# When implementing new features or refactoring
-- Always read the .aiconfig file 
-- Always implement code slowly and methodically 
-- Always test as you go
-- Always make sure rubocop passes
-- Do not add any functionality for the new feature to existing tests unless absolutely necessarry.
-
-# Examples
-- The examples must _only_ include _required_ code
-- The examples must not include any unrelated or supurflous code
-- Examples must be a single markdown file
-- Examples must use the `http` code blocks for its exampels
-- Examples must only include the minium number of examples
-- Examples must never include migrations.
-- Examples must not include a features section or similar
-- Examples must include an introduction to the example
-- Examples live in /examples/*.md