workarea-api-storefront 4.4.6

data/test/documentation/workarea/api/storefront/analytics_documentation_test.rb

@@ -0,0 +1,51 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class AnalyticsDocumentationTest < DocumentationTest
+        resource 'Analytics'
+
+        def test_and_document_saving_a_category_view
+          description 'saving a category view'
+          route storefront_api.analytics_category_view_path(category_id: ':category_id')
+          explanation 'saving a category view will be reflected in admin reports'
+
+          record_request do
+            post storefront_api.analytics_category_view_path(category_id: '12345')
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_saving_a_product_view
+          description 'saving a product view'
+          route storefront_api.analytics_product_view_path(product_id: ':product_id')
+          explanation 'saving a product view will be reflected in admin reports'
+
+          record_request do
+            post storefront_api.analytics_product_view_path(product_id: '12345')
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_saving_a_search
+          description 'Saving a search'
+          route storefront_api.analytics_search_path
+          explanation <<-EOS
+            Saving a search will be reflected in admin reports. This is intended
+            to be called once per search performed by a customer.
+          EOS
+
+          record_request do
+            post storefront_api.analytics_search_path,
+                  as: :json,
+                  params: { q: 'foo', total_results: 5 }
+
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/assets_documentation_test.rb

@@ -0,0 +1,32 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class AssetsDocumentationTest < DocumentationTest
+        resource 'Assets'
+
+        setup :set_asset
+
+        def set_asset
+          @asset = create_asset(name: 'Summer Sale Callout')
+        end
+
+        def test_and_document_showing_assets
+          description 'Showing an asset'
+          route storefront_api.asset_path(':id')
+          explanation <<-EOS
+            Use this endpoint to look up assets stored in Workarea. Often times
+            these will be referenced in content blocks.
+          EOS
+
+          record_request do
+            get storefront_api.asset_path(@asset)
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/authentication_documentation_test.rb

@@ -0,0 +1,84 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class AuthenticationDocumentationTest < DocumentationTest
+        include AuthenticationTest
+
+        resource 'Authentication'
+
+        setup :set_user
+
+        def set_user
+          @user = create_user(password: 'p@assword!')
+        end
+
+        def distance_of_time_in_words(*args)
+          ApplicationController.helpers.distance_of_time_in_words(*args)
+        end
+
+        def test_creating_an_authentication_token
+          description 'Creating an authentication token'
+          route storefront_api.authentication_tokens_path
+          explanation <<-EOS
+            Creating an authentication token is the first step in user
+            authentication. You will use this token to authenticate requests on
+            behalf of the user going forward. To get a token you can use to
+            authenticate an account, use this endpoint. You'll need the email
+            and password from the user, and we'll issue a token that can be used
+            to authenticate further requests for that customer. This token will
+            expire after #{distance_of_time_in_words(Workarea.config.authentication_token_expiration)}.
+            Tokens are also invalidated when a user changes their password. See
+            the "using an authentication token" example for how to use an
+            authentication token.
+          EOS
+
+          record_request do
+            post storefront_api.authentication_tokens_path,
+              params: { email: @user.email, password: 'p@assword!' },
+              as: :json
+
+            assert(response.ok?)
+          end
+        end
+
+        def test_using_an_authentication_token
+          description 'Using an authentication token'
+          route storefront_api.account_path
+          explanation <<-EOS
+            After obtaining an authentication token you can use it to request
+            authenticated endpoints by including it in the Authorization header
+            on the request, as demonstrated in this example.
+          EOS
+
+          auth = @user.authentication_tokens.create!
+
+          record_request do
+            get storefront_api.account_path,
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(auth.token) }
+
+            assert(response.ok?)
+          end
+        end
+
+        def test_refreshing_an_authentication_token
+          description 'Refreshing an authentication token'
+          route storefront_api.authentication_tokens_path
+          explanation <<-EOS
+            Refreshing an authentication token extends its expiration so that it
+            can continue to be used.
+          EOS
+
+          auth = @user.authentication_tokens.create!
+
+          record_request do
+            patch storefront_api.authentication_tokens_path,
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(auth.token) }
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/cart_items_documentation_test.rb

@@ -0,0 +1,104 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class CartItemsDocumentationTest < DocumentationTest
+        include AuthenticationTest
+        include OrdersTest
+
+        resource 'Cart'
+
+        setup :set_user, :set_product, :set_order
+
+        def set_user
+          @user = create_user(first_name: 'Susan', last_name: 'Baker')
+          @auth = @user.authentication_tokens.create!
+        end
+
+        def set_product
+          @product = create_product(
+            id: 'VINTEE',
+            name: 'Vintage Tee',
+            variants: [
+              { sku: 'VT001', regular: 5.to_m },
+              { sku: 'VT002', regular: 6.to_m }
+            ]
+          )
+
+          create_inventory(id: 'VT001', policy: 'standard', available: 2)
+        end
+
+        def set_order
+          @order = create_order(user_id: @user.id)
+        end
+
+        def test_and_document_adding_an_item
+          description 'Adding an item'
+          route storefront_api.cart_items_path(':cart_id')
+          explanation <<-EOS
+            Adds an item to the cart. Use the create a cart endpoint to get a
+            cart_id to use with this endpoint.
+          EOS
+
+          record_request do
+            post storefront_api.cart_items_path(@order),
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) },
+              as: :json,
+              params: {
+                product_id: @product.id,
+                sku: @product.skus.first,
+                quantity: 2
+              }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_updating_an_item
+          add_item(@order, product_id: @product.id, sku: 'VT001', quantity: 2)
+
+          description 'Updating an item'
+          route storefront_api.cart_item_path(':cart_id', ':id')
+          explanation <<-EOS
+            Updates an item in the cart. Use the create a cart endpoint to get a
+            cart ID to use with this endpoint, and use the adding an item
+            endpoint to get an ID for an item.
+          EOS
+
+          record_request do
+            patch storefront_api.cart_item_path(@order, @order.items.first),
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) },
+              as: :json,
+              params: {
+                sku: @product.skus.last,
+                quantity: 3
+              }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_deleting_an_item
+          add_item(@order, product_id: @product.id, sku: 'VT001', quantity: 2)
+
+          description 'Delete an item'
+          route storefront_api.cart_item_path(':cart_id', ':id')
+          explanation <<-EOS
+            Removes an item in the cart. Use the create a cart endpoint to get a
+            cart ID to use with this endpoint, and use the adding an item
+            endpoint to get an ID for an item.
+          EOS
+
+          record_request do
+            delete storefront_api.cart_item_path(@order, @order.items.first),
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) }
+
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/carts_documentation_test.rb

@@ -0,0 +1,121 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class CartsDocumentationTest < DocumentationTest
+        include AuthenticationTest
+        include OrdersTest
+
+        resource 'Cart'
+
+        setup :set_user, :set_product, :set_order
+
+        def set_user
+          @user = create_user(first_name: 'Susan', last_name: 'Baker')
+          @auth = @user.authentication_tokens.create!
+        end
+
+        def set_product
+          @product = create_product(
+            id: 'VINTEE',
+            name: 'Vintage Tee',
+            variants: [
+              { sku: 'VT001', regular: 5.to_m },
+              { sku: 'VT002', regular: 6.to_m }
+            ]
+          )
+
+          create_inventory(id: 'VT001', policy: 'standard', available: 2)
+        end
+
+        def set_order
+          @order = create_order(user_id: @user.id)
+          add_item(@order, product_id: @product.id, sku: 'VT001', quantity: 2)
+        end
+
+        def test_and_document_listing_carts
+          description "Listing user's carts"
+          route storefront_api.carts_path
+          explanation <<-EOS
+            You can get a listing of all of a user's open carts with this
+            endpoint. There will usually be one from the standard storefront,
+            but with the cart creation endpoint there is the potential to create
+            and manage multiple carts for a single user.
+          EOS
+
+          record_request do
+            get storefront_api.carts_path,
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_creating_a_guest_cart
+          description 'Creating a new guest cart'
+          route storefront_api.carts_path
+          explanation <<-EOS
+            Use this endpoint to create a cart. This allows the possibility of
+            multiple carts for a user.
+          EOS
+
+          record_request do
+            post storefront_api.carts_path
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_creating_a_logged_in_cart
+          description 'Creating a new cart for a user'
+          route storefront_api.carts_path
+          explanation <<-EOS
+            Here's how to create a cart for a user. This endpoint allows the
+            possibility of multiple carts for a user.
+          EOS
+
+          record_request do
+            post storefront_api.carts_path,
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_showing_a_cart
+          description 'Showing cart'
+          route storefront_api.cart_path(':id')
+          explanation <<-EOS
+            This will get details on a cart you've created with the cart
+            creation endpoint.
+          EOS
+
+          record_request do
+            get storefront_api.cart_path(@order),
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_adding_a_promo_code
+          description 'Adding a promo code'
+          route storefront_api.add_promo_code_to_cart_path(':id')
+          explanation 'This endpoint will add promo codes to the cart'
+
+          create_order_total_discount(promo_codes: %w(10OFF))
+
+          record_request do
+            post storefront_api.add_promo_code_to_cart_path(@order),
+              as: :json,
+              headers: { 'HTTP_AUTHORIZATION' => encode_credentials(@auth.token) },
+              params: { promo_code: '10OFF' }
+
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/categories_documentation_test.rb

@@ -0,0 +1,90 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class CategoriesDocumentationTest < DocumentationTest
+        resource 'Categories'
+
+        setup :set_product
+        setup :set_category
+        setup :set_taxonomy
+        setup :set_content
+
+        def set_product
+          @product = create_product(
+            name: 'Sweet Shirt',
+            filters:  { size: %w[Small Medium Large], color: 'Blue' },
+            variants: [{ sku: 'SKU', details: { color: 'Blue' }, regular: 2.to_m }],
+            details: { size: 'Small', color: 'Red' },
+            images: [{ image: product_image_file, option: 'Blue' }]
+          )
+        end
+
+        def set_category
+          @category = create_category(
+            name: 'Shirts',
+            product_ids: [@product.id],
+            terms_facets: %w(Size Color)
+          )
+        end
+
+        def set_taxonomy
+          first_level = create_taxon(name: 'Mens')
+          @taxon = first_level.children.create!(navigable: @category)
+        end
+
+        def set_content
+          content = Content.for(@category)
+          content.blocks.build(
+            area: :above_results,
+            type: :text,
+            data: { text: 'text' }
+          )
+          content.blocks.build(
+            area: :below_results,
+            type: :text,
+            data: { text: 'text' }
+          )
+          content.save!
+        end
+
+        def test_and_document_index
+          description 'Showing a listing of categories'
+          route storefront_api.categories_path
+          parameter 'page', 'Page number'
+          explanation <<-EOS
+            This endpoint will give you a paginated list of all active
+            categories, that is, all categories that could be shown on the
+            storefront.
+          EOS
+
+          create_category(name: 'Pants')
+
+          record_request do
+            get storefront_api.categories_path(page: '1')
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_show
+          description 'Showing a category'
+          route storefront_api.category_path(':slug')
+          parameter 'sort', 'Sort by'
+          parameter 'page', 'Page number'
+          parameter ':facet_name', 'Each facet setup on the category will have a corresponding parameter'
+          explanation <<-EOS
+            This endpoint includes everything you need to render a category,
+            including any associated content, products, and filters.
+          EOS
+
+          record_request do
+            get storefront_api.category_path(@category, page: '1', sort: 'price_desc')
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/checkouts_documentation_test.rb

@@ -0,0 +1,142 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class CheckoutsDocumentationTest < DocumentationTest
+        include OrdersTest
+
+        resource 'Checkout'
+
+        setup :set_product, :set_order, :set_checkout_data
+
+        def set_product
+          @product = create_product(
+            id: 'VINTEE',
+            name: 'Vintage Tee',
+            variants: [
+              { sku: 'VT001', regular: 5.to_m },
+              { sku: 'VT002', regular: 6.to_m }
+            ]
+          )
+
+          create_inventory(id: 'VT001', policy: 'standard', available: 2)
+        end
+
+        def set_order
+          @order = create_order(email: 'sbaker@workarea.com')
+          add_item(@order, product_id: @product.id, sku: 'VT001', quantity: 2)
+        end
+
+        def set_checkout_data
+          create_shipping_service(name: 'Standard', rates: [{ price: 5.to_m }])
+          create_shipping_service(name: 'Express', rates: [{ price: 10.to_m }])
+          create_shipping_service(name: 'Overnight', rates: [{ price: 20.to_m }])
+        end
+
+        def address
+          {
+            first_name: 'Susan',
+            last_name: 'Baker',
+            street: '350 Fifth Avenue',
+            city: 'New York',
+            region: 'NY',
+            country: 'US',
+            postal_code: '10118',
+            phone_number: '6465552390'
+          }
+        end
+
+        def test_and_document_show
+          description 'Showing a checkout'
+          route storefront_api.checkout_path(':id')
+          explanation <<-EOS
+            This will give you overview of the state of checkout for the
+            associated order ID. It includes full order information, as well
+            as summary information for each step of checkout.
+          EOS
+
+          record_request do
+            get storefront_api.checkout_path(@order)
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_update
+          description 'Updating a checkout'
+          route storefront_api.checkout_path(':id')
+          explanation <<-EOS
+            Use this endpoint to make updates to checkout. This will typically
+            mean setting addresses and shipping options for the checkout.
+          EOS
+
+          record_request do
+            patch storefront_api.checkout_path(@order),
+              as: :json,
+              params: {
+                email: 'susanb@workarea.com',
+                shipping_address: address,
+                billing_address: address,
+                shipping_service: 'Express'
+              }
+
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_complete
+          description 'Completing a checkout'
+          route storefront_api.complete_checkout_path(':id')
+          explanation <<-EOS
+            This endpoint completes checkout and places the order. Payment
+            tender information is required at this point, and should be included
+            with this request.
+          EOS
+
+          patch storefront_api.checkout_path(@order),
+            as: :json,
+            params: {
+              email: 'susanb@workarea.com',
+              shipping_address: address,
+              billing_address: address,
+              shipping_service: 'Express'
+            }
+
+          order = JSON.parse(response.body)['order']
+
+          record_request do
+            post storefront_api.complete_checkout_path(order['id']),
+              as: :json,
+              params: {
+                payment: 'new_card',
+                credit_card: {
+                  number: '4111111111111111',
+                  month: '3',
+                  year: Time.now.year + 2,
+                  cvv: '123'
+                }
+              }
+            assert_equal(200, response.status)
+          end
+        end
+
+        def test_and_document_reset
+          description 'Showing a checkout'
+          route storefront_api.reset_checkout_path(':id')
+          explanation <<-EOS
+            This endpoint resets the checkout by wiping all private information
+            from the order and it's associated models. Use it for handling
+            timeouts, logouts, and any other situation where you want to ensure
+            the safety of the customer's information.
+          EOS
+
+          record_request do
+            get storefront_api.reset_checkout_path(@order)
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end

data/test/documentation/workarea/api/storefront/contacts_documentation_test.rb

@@ -0,0 +1,39 @@
+require 'test_helper'
+require 'workarea/api/documentation_test'
+
+module Workarea
+  module Api
+    module Storefront
+      class ContactsDocumentationTest < DocumentationTest
+        resource 'Contacts'
+
+        setup :set_contact_params
+
+        def set_contact_params
+          @contact_params = {
+            name: 'Name',
+            email: 'email@example.com',
+            order_id: 'OrderID',
+            subject: :orders,
+            message: 'Message'
+          }
+        end
+
+        def test_and_document_create
+          description 'Creating a contact'
+          route storefront_api.contacts_path
+          explanation <<-EOS
+            This endpoints creates a customer service inquiry on behalf of the
+            customer, and will send an email to the address in
+            Workarea.config.email_to
+          EOS
+
+          record_request do
+            post storefront_api.contacts_path, params: @contact_params, as: :json
+            assert_equal(200, response.status)
+          end
+        end
+      end
+    end
+  end
+end