Add behaviors for the various library modules

This should allow consumers of the shortcut api library to safely
mock the behavior with Hammox. On this end, we have confidence that
the behaviors are implemented

lib/epics.ex

@@ -1,6 +1,7 @@
 defmodule ShortcutApi.Epics do
   import ShortcutApi.ApiHelpers
 
+  @behaviour ShortcutApi.EpicsBehavior
   @moduledoc """
   API wrapper for Shortcut Epics endpoints.
   See: https://developer.shortcut.com/api/rest/v3#Epics
@@ -168,3 +169,29 @@ defmodule ShortcutApi.Epics do
     make_request(:get, "/epic-workflow/states/#{state_id}", token)
   end
 end
+
+defmodule ShortcutApi.EpicsBehavior do
+  @moduledoc """
+  A behaviour for interacting with Shortcut Epics API endpoints.
+
+  This module defines the required callbacks for operations related to epics,
+  including retrieving, creating, updating, deleting, and managing epic states
+  and statistics. Implementations of this behaviour must provide the necessary
+  logic to handle interactions with the Shortcut API.
+
+  All callbacks require a valid Shortcut API token.
+  """
+  @callback get_epic(token :: String.t(), epic_id :: pos_integer()) ::
+              {:ok, map()} | {:error, any()}
+  @callback create_epic(token :: String.t(), params :: map()) :: {:ok, map()} | {:error, any()}
+  @callback update_epic(token :: String.t(), epic_id :: pos_integer(), params :: map()) ::
+              {:ok, map()} | {:error, any()}
+  @callback delete_epic(token :: String.t(), epic_id :: pos_integer()) ::
+              {:ok, map()} | {:error, any()}
+  @callback list_epics(token :: String.t()) :: {:ok, list(map())} | {:error, any()}
+  @callback get_epic_workflow(token :: String.t()) :: {:ok, map()} | {:error, any()}
+  @callback get_epic_stats(token :: String.t(), epic_id :: pos_integer()) ::
+              {:ok, map()} | {:error, any()}
+  @callback get_epic_state(token :: String.t(), state_id :: pos_integer()) ::
+              {:ok, map()} | {:error, any()}
+end

lib/projects.ex

@@ -1,6 +1,7 @@
 defmodule ShortcutApi.Projects do
   import ShortcutApi.ApiHelpers
 
+  @behaviour ShortcutApi.ProjectsBehavior
   @moduledoc """
   API wrapper for Shortcut Projects endpoints.
   See: https://developer.shortcut.com/api/rest/v3#Projects
@@ -112,3 +113,15 @@ defmodule ShortcutApi.Projects do
     make_request(:delete, "/projects/#{project_id}", token)
   end
 end
+
+defmodule ShortcutApi.ProjectsBehavior do
+  @moduledoc """
+    The Projects behaviour.
+  """
+
+  @callback list_projects(String.t()) :: {:ok, map() | list(map())} | {:error, any()}
+  @callback get_project(String.t(), pos_integer()) :: {:ok, map()} | {:error, any()}
+  @callback create_project(String.t(), map()) :: {:ok, map()} | {:error, any()}
+  @callback update_project(String.t(), pos_integer(), map()) :: {:ok, map()} | {:error, any()}
+  @callback delete_project(String.t(), pos_integer()) :: {:ok, map()} | {:error, any()}
+end

lib/stories.ex

@@ -1,4 +1,5 @@
 defmodule ShortcutApi.Stories do
+  @behaviour ShortcutApi.StoriesBehavior
   import ShortcutApi.ApiHelpers
 
   @moduledoc """
@@ -96,3 +97,36 @@ defmodule ShortcutApi.Stories do
     make_request(:delete, "/stories/#{story_id}", token)
   end
 end
+
+defmodule ShortcutApi.StoriesBehavior do
+  @moduledoc """
+  Behavior for Shortcut API Stories operations.
+
+  This module defines the callbacks required for interacting with
+  Shortcut Stories API endpoints. Implementations of this behavior
+  should provide the logic for each function to handle API requests
+  according to the Shortcut API documentation.
+
+  Each function requires a valid Shortcut API token and operates on
+  story data, facilitating creating, retrieving, updating, and
+  deleting stories.
+
+  ## Callbacks
+
+  * `get_story/2`: Retrieves a single story by its ID.
+  * `create_story/2`: Creates a new story with the provided parameters.
+  * `update_story/3`: Updates an existing story identified by its ID.
+  * `delete_story/2`: Deletes a story by its ID.
+  """
+  @callback get_story(token :: String.t(), story_id :: pos_integer()) ::
+              {:ok, map() | list(map())} | {:error, any()}
+
+  @callback create_story(token :: String.t(), params :: map()) ::
+              {:ok, map() | list(map())} | {:error, any()}
+
+  @callback update_story(token :: String.t(), story_id :: pos_integer(), params :: map()) ::
+              {:ok, map() | list(map())} | {:error, any()}
+
+  @callback delete_story(token :: String.t(), story_id :: pos_integer()) ::
+              {:ok, map() | list(map())} | {:error, any()}
+end

mix.exs

@@ -47,12 +47,13 @@ defmodule ShortcutApiEx.MixProject do
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
-      {:req, "~> 0.5.0"},
-      {:jason, "~> 1.4"},
       {:bypass, "~> 2.1", only: :test},
-      {:plug_cowboy, "~> 2.5", only: :test},
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
-      {:ex_doc, "~> 0.34", only: :dev, runtime: false}
+      {:ex_doc, "~> 0.34", only: :dev, runtime: false},
+      {:hammox, "~> 0.7", only: :test},
+      {:jason, "~> 1.4"},
+      {:plug_cowboy, "~> 2.5", only: :test},
+      {:req, "~> 0.5.0"}
     ]
   end
 

mix.lock

@@ -9,16 +9,20 @@
   "ex_doc": {:hex, :ex_doc, "0.35.1", "de804c590d3df2d9d5b8aec77d758b00c814b356119b3d4455e4b8a8687aecaf", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "2121c6402c8d44b05622677b761371a759143b958c6c19f6558ff64d0aed40df"},
   "file_system": {:hex, :file_system, "1.0.1", "79e8ceaddb0416f8b8cd02a0127bdbababe7bf4a23d2a395b983c1f8b3f73edd", [:mix], [], "hexpm", "4414d1f38863ddf9120720cd976fce5bdde8e91d8283353f0e31850fa89feb9e"},
   "finch": {:hex, :finch, "0.19.0", "c644641491ea854fc5c1bbaef36bfc764e3f08e7185e1f084e35e0672241b76d", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:mint, "~> 1.6.2 or ~> 1.7", [hex: :mint, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.4 or ~> 1.0", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:nimble_pool, "~> 1.1", [hex: :nimble_pool, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "fc5324ce209125d1e2fa0fcd2634601c52a787aff1cd33ee833664a5af4ea2b6"},
+  "hammox": {:hex, :hammox, "0.7.0", "a49dc95e0a78e1c38db11c2b6eadff38f25418ef92ecf408bd90d95d459f35a2", [:mix], [{:mox, "~> 1.0", [hex: :mox, repo: "hexpm", optional: false]}, {:ordinal, "~> 0.1", [hex: :ordinal, repo: "hexpm", optional: false]}, {:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "5e228c4587f23543f90c11394957878178c489fad46da421c37ca696e37dd91b"},
   "hpax": {:hex, :hpax, "1.0.0", "28dcf54509fe2152a3d040e4e3df5b265dcb6cb532029ecbacf4ce52caea3fd2", [:mix], [], "hexpm", "7f1314731d711e2ca5fdc7fd361296593fc2542570b3105595bb0bc6d0fad601"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
   "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.0", "74bb8348c9b3a51d5c589bf5aebb0466a84b33274150e3b6ece1da45584afc82", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "49159b7d7d999e836bedaf09dcf35ca18b312230cf901b725a64f3f42e407983"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
   "mime": {:hex, :mime, "2.0.6", "8f18486773d9b15f95f4f4f1e39b710045fa1de891fada4516559967276e4dc2", [:mix], [], "hexpm", "c9945363a6b26d747389aac3643f8e0e09d30499a138ad64fe8fd1d13d9b153e"},
   "mint": {:hex, :mint, "1.6.2", "af6d97a4051eee4f05b5500671d47c3a67dac7386045d87a904126fd4bbcea2e", [:mix], [{:castore, "~> 0.1.0 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:hpax, "~> 0.1.1 or ~> 0.2.0 or ~> 1.0", [hex: :hpax, repo: "hexpm", optional: false]}], "hexpm", "5ee441dffc1892f1ae59127f74afe8fd82fda6587794278d924e4d90ea3d63f9"},
+  "mox": {:hex, :mox, "1.2.0", "a2cd96b4b80a3883e3100a221e8adc1b98e4c3a332a8fc434c39526babafd5b3", [:mix], [{:nimble_ownership, "~> 1.0", [hex: :nimble_ownership, repo: "hexpm", optional: false]}], "hexpm", "c7b92b3cc69ee24a7eeeaf944cd7be22013c52fcb580c1f33f50845ec821089a"},
   "nimble_options": {:hex, :nimble_options, "1.1.1", "e3a492d54d85fc3fd7c5baf411d9d2852922f66e69476317787a7b2bb000a61b", [:mix], [], "hexpm", "821b2470ca9442c4b6984882fe9bb0389371b8ddec4d45a9504f00a66f650b44"},
+  "nimble_ownership": {:hex, :nimble_ownership, "1.0.0", "3f87744d42c21b2042a0aa1d48c83c77e6dd9dd357e425a038dd4b49ba8b79a1", [:mix], [], "hexpm", "7c16cc74f4e952464220a73055b557a273e8b1b7ace8489ec9d86e9ad56cb2cc"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
   "nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
+  "ordinal": {:hex, :ordinal, "0.2.0", "d3eda0cb04ee1f0ca0aae37bf2cf56c28adce345fe56a75659031b6068275191", [:mix], [], "hexpm", "defca8f10dee9f03a090ed929a595303252700a9a73096b6f2f8d88341690d65"},
   "plug": {:hex, :plug, "1.16.1", "40c74619c12f82736d2214557dedec2e9762029b2438d6d175c5074c933edc9d", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.3 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "a13ff6b9006b03d7e33874945b2755253841b238c34071ed85b0e86057f8cddc"},
   "plug_cowboy": {:hex, :plug_cowboy, "2.7.2", "fdadb973799ae691bf9ecad99125b16625b1c6039999da5fe544d99218e662e4", [:mix], [{:cowboy, "~> 2.7", [hex: :cowboy, repo: "hexpm", optional: false]}, {:cowboy_telemetry, "~> 0.3", [hex: :cowboy_telemetry, repo: "hexpm", optional: false]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}], "hexpm", "245d8a11ee2306094840c000e8816f0cbed69a23fc0ac2bcf8d7835ae019bb2f"},
   "plug_crypto": {:hex, :plug_crypto, "2.1.0", "f44309c2b06d249c27c8d3f65cfe08158ade08418cf540fd4f72d4d6863abb7b", [:mix], [], "hexpm", "131216a4b030b8f8ce0f26038bc4421ae60e4bb95c5cf5395e1421437824c4fa"},

test/epics_test.exs

@@ -9,7 +9,11 @@ defmodule ShortcutApi.EpicsTest do
     {:ok, bypass: bypass}
   end
 
-  test "get_epic/2", %{bypass: bypass} do
+  setup_all do
+    Hammox.protect(ShortcutApi.Epics, ShortcutApi.EpicsBehavior)
+  end
+
+  test "get_epic/2", %{bypass: bypass, get_epic_2: get_epic} do
     epic_id = 123
 
     Bypass.expect(bypass, "GET", "/api/v3/epics/#{epic_id}", fn conn ->
@@ -21,12 +25,12 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, epic} = ShortcutApi.Epics.get_epic("fake-token", epic_id)
+    {:ok, epic} = get_epic.("fake-token", epic_id)
     assert epic["id"] == epic_id
     assert epic["name"] == "Test Epic"
   end
 
-  test "create_epic/2", %{bypass: bypass} do
+  test "create_epic/2", %{bypass: bypass, create_epic_2: create_epic} do
     epic_params = %{"name" => "New Epic", "workflow_state_id" => 789}
 
     Bypass.expect(bypass, "POST", "/api/v3/epics", fn conn ->
@@ -40,12 +44,12 @@ defmodule ShortcutApi.EpicsTest do
       |> Plug.Conn.resp(201, Jason.encode!(response))
     end)
 
-    {:ok, epic} = ShortcutApi.Epics.create_epic("fake-token", epic_params)
+    {:ok, epic} = create_epic.("fake-token", epic_params)
     assert epic["name"] == "New Epic"
     assert epic["workflow_state_id"] == 789
   end
 
-  test "update_epic/3", %{bypass: bypass} do
+  test "update_epic/3", %{bypass: bypass, update_epic_3: update_epic} do
     epic_id = 123
     update_params = %{"name" => "Updated Epic"}
 
@@ -61,12 +65,12 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, epic} = ShortcutApi.Epics.update_epic("fake-token", epic_id, update_params)
+    {:ok, epic} = update_epic.("fake-token", epic_id, update_params)
     assert epic["id"] == epic_id
     assert epic["name"] == "Updated Epic"
   end
 
-  test "delete_epic/2", %{bypass: bypass} do
+  test "delete_epic/2", %{bypass: bypass, delete_epic_2: delete_epic} do
     epic_id = 123
 
     Bypass.expect(bypass, "DELETE", "/api/v3/epics/#{epic_id}", fn conn ->
@@ -75,10 +79,10 @@ defmodule ShortcutApi.EpicsTest do
       |> Plug.Conn.resp(200, Jason.encode!(%{}))
     end)
 
-    assert {:ok, %{}} = ShortcutApi.Epics.delete_epic("fake-token", epic_id)
+    assert {:ok, %{}} = delete_epic.("fake-token", epic_id)
   end
 
-  test "list_epics/1", %{bypass: bypass} do
+  test "list_epics/1", %{bypass: bypass, list_epics_1: list_epics} do
     Bypass.expect(bypass, "GET", "/api/v3/epics", fn conn ->
       conn
       |> Plug.Conn.put_resp_content_type("application/json")
@@ -91,13 +95,13 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, epics} = ShortcutApi.Epics.list_epics("fake-token")
+    {:ok, epics} = list_epics.("fake-token")
     assert length(epics) == 2
     assert Enum.at(epics, 0)["name"] == "Epic 1"
     assert Enum.at(epics, 1)["name"] == "Epic 2"
   end
 
-  test "get_epic_workflow/1", %{bypass: bypass} do
+  test "get_epic_workflow/1", %{bypass: bypass, get_epic_workflow_1: get_epic_workflow} do
     Bypass.expect(bypass, "GET", "/api/v3/epic-workflow", fn conn ->
       conn
       |> Plug.Conn.put_resp_content_type("application/json")
@@ -113,12 +117,12 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, workflow} = ShortcutApi.Epics.get_epic_workflow("fake-token")
+    {:ok, workflow} = get_epic_workflow.("fake-token")
     assert length(workflow["states"]) == 3
     assert Enum.at(workflow["states"], 1)["name"] == "In Progress"
   end
 
-  test "get_epic_stats/2", %{bypass: bypass} do
+  test "get_epic_stats/2", %{bypass: bypass, get_epic_stats_2: get_epic_stats} do
     epic_id = 123
 
     Bypass.expect(bypass, "GET", "/api/v3/epics/#{epic_id}/stats", fn conn ->
@@ -136,12 +140,12 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, stats} = ShortcutApi.Epics.get_epic_stats("fake-token", epic_id)
+    {:ok, stats} = get_epic_stats.("fake-token", epic_id)
     assert stats["num_points"] == 10
     assert stats["num_stories"] == 5
   end
 
-  test "get_epic_state/2", %{bypass: bypass} do
+  test "get_epic_state/2", %{bypass: bypass, get_epic_state_2: get_epic_state} do
     state_id = 123
 
     Bypass.expect(bypass, "GET", "/api/v3/epic-workflow/states/#{state_id}", fn conn ->
@@ -158,7 +162,7 @@ defmodule ShortcutApi.EpicsTest do
       )
     end)
 
-    {:ok, state} = ShortcutApi.Epics.get_epic_state("fake-token", state_id)
+    {:ok, state} = get_epic_state.("fake-token", state_id)
     assert state["id"] == state_id
     assert state["name"] == "In Progress"
     assert state["type"] == "started"

test/projects_test.exs

@@ -9,7 +9,11 @@ defmodule ShortcutApi.ProjectsTest do
     {:ok, bypass: bypass}
   end
 
-  test "list_projects/1", %{bypass: bypass} do
+  setup_all do
+    Hammox.protect(ShortcutApi.Projects, ShortcutApi.ProjectsBehavior)
+  end
+
+  test "list_projects/1", %{bypass: bypass, list_projects_1: list_projects} do
     Bypass.expect(bypass, "GET", "/api/v3/projects", fn conn ->
       conn
       |> Plug.Conn.put_resp_content_type("application/json")
@@ -22,13 +26,13 @@ defmodule ShortcutApi.ProjectsTest do
       )
     end)
 
-    {:ok, projects} = ShortcutApi.Projects.list_projects("fake-token")
+    {:ok, projects} = list_projects.("fake-token")
     assert length(projects) == 2
     assert Enum.at(projects, 0)["name"] == "Project 1"
     assert Enum.at(projects, 1)["name"] == "Project 2"
   end
 
-  test "get_project/2", %{bypass: bypass} do
+  test "get_project/2", %{bypass: bypass, get_project_2: get_project} do
     project_id = 123
 
     Bypass.expect(bypass, "GET", "/api/v3/projects/#{project_id}", fn conn ->
@@ -40,12 +44,12 @@ defmodule ShortcutApi.ProjectsTest do
       )
     end)
 
-    {:ok, project} = ShortcutApi.Projects.get_project("fake-token", project_id)
+    {:ok, project} = get_project.("fake-token", project_id)
     assert project["id"] == project_id
     assert project["name"] == "Test Project"
   end
 
-  test "create_project/2", %{bypass: bypass} do
+  test "create_project/2", %{bypass: bypass, create_project_2: create_project} do
     project_params = %{"name" => "New Project"}
 
     Bypass.expect(bypass, "POST", "/api/v3/projects", fn conn ->
@@ -59,12 +63,12 @@ defmodule ShortcutApi.ProjectsTest do
       |> Plug.Conn.resp(201, Jason.encode!(response))
     end)
 
-    {:ok, project} = ShortcutApi.Projects.create_project("fake-token", project_params)
+    {:ok, project} = create_project.("fake-token", project_params)
     assert project["name"] == "New Project"
     assert project["id"] == 456
   end
 
-  test "update_project/3", %{bypass: bypass} do
+  test "update_project/3", %{bypass: bypass, update_project_3: update_project} do
     project_id = 123
     update_params = %{"name" => "Updated Project"}
 
@@ -80,12 +84,12 @@ defmodule ShortcutApi.ProjectsTest do
       )
     end)
 
-    {:ok, project} = ShortcutApi.Projects.update_project("fake-token", project_id, update_params)
+    {:ok, project} = update_project.("fake-token", project_id, update_params)
     assert project["id"] == project_id
     assert project["name"] == "Updated Project"
   end
 
-  test "delete_project/2", %{bypass: bypass} do
+  test "delete_project/2", %{bypass: bypass, delete_project_2: delete_project} do
     project_id = 123
 
     Bypass.expect(bypass, "DELETE", "/api/v3/projects/#{project_id}", fn conn ->
@@ -94,6 +98,6 @@ defmodule ShortcutApi.ProjectsTest do
       |> Plug.Conn.resp(200, Jason.encode!(%{}))
     end)
 
-    assert {:ok, %{}} = ShortcutApi.Projects.delete_project("fake-token", project_id)
+    assert {:ok, %{}} = delete_project.("fake-token", project_id)
   end
 end