feat(products): add product API endpoints

Add /api/v1/products CRUD endpoints addressed by code, backed by the product
services and query: create, update (code is immutable and not permitted),
show, paginated index and soft delete.

Author: rsempe

app/controllers/api/v1/products_controller.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class ProductsController < Api::BaseController
+      def create
+        result = Products::CreateService.call(
+          organization: current_organization,
+          params: input_params.to_h.symbolize_keys
+        )
+
+        if result.success?
+          render_product(result.product)
+        else
+          render_error_response(result)
+        end
+      end
+
+      def update
+        product = current_organization.products.find_by(code: params[:code])
+        result = Products::UpdateService.call(product:, params: update_params.to_h.symbolize_keys)
+
+        if result.success?
+          render_product(result.product)
+        else
+          render_error_response(result)
+        end
+      end
+
+      def destroy
+        product = current_organization.products.find_by(code: params[:code])
+        result = Products::DestroyService.call(product:)
+
+        if result.success?
+          render_product(result.product)
+        else
+          render_error_response(result)
+        end
+      end
+
+      def show
+        product = current_organization.products.find_by(code: params[:code])
+
+        return not_found_error(resource: "product") unless product
+
+        render_product(product)
+      end
+
+      def index
+        result = ProductsQuery.call(
+          organization: current_organization,
+          pagination: {
+            page: params[:page],
+            limit: params[:per_page] || PER_PAGE
+          }
+        )
+
+        if result.success?
+          render(
+            json: ::CollectionSerializer.new(
+              result.products,
+              ::V1::ProductSerializer,
+              collection_name: "products",
+              meta: pagination_metadata(result.products)
+            )
+          )
+        else
+          render_error_response(result)
+        end
+      end
+
+      private
+
+      def input_params
+        params.require(:product).permit(
+          :name,
+          :code,
+          :description,
+          :invoice_display_name
+        )
+      end
+
+      def update_params
+        params.require(:product).permit(
+          :name,
+          :description,
+          :invoice_display_name
+        )
+      end
+
+      def render_product(product)
+        render(json: ::V1::ProductSerializer.new(product, root_name: "product"))
+      end
+
+      def resource_name
+        "product"
+      end
+    end
+  end
+end

app/models/api_key.rb

@@ -7,7 +7,7 @@ class ApiKey < ApplicationRecord
     activity_log add_on analytic api_log billable_metric coupon applied_coupon credit_note customer_usage
     customer event fee invoice organization order order_form payment payment_receipt payment_request payment_method plan subscription lifetime_usage
     tax wallet wallet_transaction webhook_endpoint webhook_jwt_public_key invoice_custom_section
-    billing_entity alert feature security_log quote
+    billing_entity alert feature security_log quote product
   ].freeze
 
   MODES = %w[read write].freeze

config/routes.rb

@@ -179,6 +179,7 @@
           end
         end
       end
+      resources :products, param: :code, code: /.*/, only: %i[index show create update destroy]
       resources :taxes, param: :code, code: /.*/
       resources :wallet_transactions, only: %i[create show] do
         post :payment_url, on: :member

spec/requests/api/v1/products_controller_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Api::V1::ProductsController do
+  let(:organization) { create(:organization) }
+
+  describe "POST /api/v1/products" do
+    subject { post_with_token(organization, "/api/v1/products", {product: create_params}) }
+
+    let(:create_params) do
+      {
+        name: "Cards",
+        code: "cards",
+        description: "Card products",
+        invoice_display_name: "Cards"
+      }
+    end
+
+    include_examples "requires API permission", "product", "write"
+
+    it "creates a product" do
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:product][:lago_id]).to be_present
+      expect(json[:product][:name]).to eq("Cards")
+      expect(json[:product][:code]).to eq("cards")
+      expect(json[:product][:description]).to eq("Card products")
+      expect(json[:product][:invoice_display_name]).to eq("Cards")
+    end
+
+    context "when the code is already used" do
+      before { create(:product, organization:, code: "cards") }
+
+      it "returns a validation error" do
+        subject
+
+        expect(response).to have_http_status(:unprocessable_entity)
+      end
+    end
+  end
+
+  describe "PUT /api/v1/products/:code" do
+    subject { put_with_token(organization, "/api/v1/products/#{product.code}", {product: update_params}) }
+
+    let(:product) { create(:product, organization:, name: "Before") }
+    let(:update_params) { {name: "After"} }
+
+    include_examples "requires API permission", "product", "write"
+
+    it "updates the product" do
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:product][:name]).to eq("After")
+      expect(json[:product][:code]).to eq(product.code)
+    end
+
+    context "when the product does not exist" do
+      subject { put_with_token(organization, "/api/v1/products/unknown", {product: update_params}) }
+
+      it "returns a not found error" do
+        subject
+
+        expect(response).to be_not_found_error("product")
+      end
+    end
+  end
+
+  describe "GET /api/v1/products/:code" do
+    subject { get_with_token(organization, "/api/v1/products/#{product.code}") }
+
+    let(:product) { create(:product, organization:) }
+
+    include_examples "requires API permission", "product", "read"
+
+    it "returns the product" do
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:product][:lago_id]).to eq(product.id)
+      expect(json[:product][:code]).to eq(product.code)
+    end
+
+    context "when the product does not exist" do
+      subject { get_with_token(organization, "/api/v1/products/unknown") }
+
+      it "returns a not found error" do
+        subject
+
+        expect(response).to be_not_found_error("product")
+      end
+    end
+
+    context "when the product belongs to another organization" do
+      let(:product) { create(:product) }
+
+      it "returns a not found error" do
+        subject
+
+        expect(response).to be_not_found_error("product")
+      end
+    end
+  end
+
+  describe "GET /api/v1/products" do
+    subject { get_with_token(organization, "/api/v1/products?page=1&per_page=1") }
+
+    before { create(:product, organization:) }
+
+    include_examples "requires API permission", "product", "read"
+
+    it "returns the paginated products" do
+      create(:product, organization:)
+
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:products].count).to eq(1)
+      expect(json[:meta][:total_count]).to eq(2)
+      expect(json[:products].first[:lago_id]).to be_present
+    end
+
+    it "does not return products from other organizations" do
+      other = create(:product)
+
+      subject
+
+      expect(json[:products].map { it[:lago_id] }).not_to include(other.id)
+    end
+  end
+
+  describe "DELETE /api/v1/products/:code" do
+    subject { delete_with_token(organization, "/api/v1/products/#{product.code}") }
+
+    let(:product) { create(:product, organization:) }
+
+    include_examples "requires API permission", "product", "write"
+
+    it "soft deletes the product" do
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:product][:lago_id]).to eq(product.id)
+      expect(product.reload).to be_discarded
+    end
+
+    context "when the product does not exist" do
+      subject { delete_with_token(organization, "/api/v1/products/unknown") }
+
+      it "returns a not found error" do
+        subject
+
+        expect(response).to be_not_found_error("product")
+      end
+    end
+  end
+end