Major release 1.0.0

.github/workflows/elixir.yml

@@ -32,8 +32,6 @@ jobs:
         restore-keys: ${{ runner.os }}-mix-
     - name: Install dependencies
       run: mix deps.get
-    - name: Check format
-      run: mix format --check-formatted
     - name: Check linter
       run: mix credo --strict -a
     - name: Run tests

.github/workflows/main.yml

@@ -0,0 +1,101 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches:
+      - master
+      - release/**
+
+  pull_request:
+
+env:
+  MIX_ENV: test
+
+jobs:
+  test:
+    name: Test (Elixir ${{ matrix.elixir }}, OTP ${{ matrix.otp }})
+
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        # https://hexdocs.pm/elixir/compatibility-and-deprecations.html#compatibility-between-elixir-and-erlang-otp
+        include:
+          # Newest supported Elixir/Erlang pair.
+          - elixir: '1.15'
+            otp: '26.0'
+            lint: true
+            dialyzer: true
+
+          # One version before the last supported one.
+          - elixir: '1.14.5'
+            otp: '25.3'
+
+    steps:
+    - name: Check out this repository
+      uses: actions/checkout@v3
+
+    - name: Setup Elixir and Erlang
+      uses: erlef/setup-beam@v1
+      with:
+        elixir-version: ${{ matrix.elixir }}
+        otp-version: ${{ matrix.otp }}
+
+    # We need to manually restore and then save, so that we can save the "_build" directory
+    # *without* the Elixir compiled code in it.
+    - name: Restore Mix dependencies cache
+      uses: actions/cache/restore@v3
+      id: mix-deps-cache
+      with:
+        path: |
+          _build
+          deps
+        key: |
+          ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-mix-${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-mix-
+
+    - name: Install and compile Mix dependencies
+      if: steps.mix-deps-cache.outputs.cache-hit != 'true'
+      run: mix do deps.get, deps.compile
+
+    - name: Save Mix dependencies cache
+      uses: actions/cache/save@v3
+      if: steps.mix-deps-cache.outputs.cache-hit != 'true'
+      with:
+        path: |
+          _build
+          deps
+        key: |
+          ${{ steps.mix-deps-cache.outputs.cache-primary-key }}
+
+    - name: Check formatting
+      if: matrix.lint
+      run: mix format --check-formatted
+
+    - name: Check compiler warnings
+      if: matrix.lint
+      run: mix compile --warnings-as-errors
+
+    - name: Run tests
+      run: mix test
+
+    - name: Retrieve PLT Cache
+      uses: actions/cache@v3
+      if: matrix.dialyzer
+      id: plt-cache
+      with:
+        path: plts
+        key: |
+          ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-plts-${{ hashFiles(format('{0}{1}', github.workspace, '/mix.lock')) }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.otp }}-${{ matrix.elixir }}-plts-
+
+    - name: Create PLTs
+      if: steps.plt-cache.outputs.cache-hit != 'true' && matrix.dialyzer
+      run: |
+        mkdir -p plts
+        mix dialyzer --plt
+
+    - name: Run dialyzer
+      if: matrix.dialyzer
+      run: mix dialyzer --no-check --halt-exit-status

.gitignore

@@ -22,6 +22,9 @@ erl_crash.dump
 # Ignore package tarball (built via "mix hex.build").
 workos-*.tar
 
-
 # Temporary files for e.g. tests
 /tmp
+
+# Dialyzer 
+/plts/*.plt
+/plts/*.plt.hash

README.md

@@ -14,53 +14,35 @@ Add this package to the list of dependencies in your `mix.exs` file:
 
 ```ex
 def deps do
-  [{:workos, "~> 0.4.0"}]
+  [{:workos, "~> 1.0.0"}]
 end
 ```
-The hex package can be found here: https://hex.pm/packages/workos
 
 ## Configuration
 
-The WorkOS API relies on two configuration parameters, the `client_id` and the `api_key`. There are two ways to configure these values with this package.
-
-### Recommended Method
-In your `config/config.exs` file you can set the `:client_id` and `:api_key` scoped to `:workos` to be used globally by default across the SDK:
+### Configure WorkOS API key & client ID on your app config
 
 ```ex
-config :workos,
-  client_id: "project_12345"
-  api_key: "sk_12345",
+config :workos, WorkOS.Client,
+      api_key: "sk_example_123456789",
+      client_id: "client_123456789"
 ```
 
-Ideally, you should use environment variables to store protected keys like your `:api_key` like so:
-
-```ex
-config :workos,
-  client_id: System.get_env("WORKOS_CLIENT_ID"),
-  api_key: System.get_env("WORKOS_API_KEY")
-```
+The only required config option is `:api_key` and `:client_id`. 
 
-### Opts Method
-Alternatively, you can override or avoid using these globally configured variables by passing a `:api_key` or `:client_id` directly to SDK methods via the optional `opts` parameter available on all methods:
+By default, this library uses [Tesla](https://github.com/elixir-tesla/tesla) but it can be replaced via the `:client` option, according to the `WorkOS.Client` module behavior. 
 
-```ex
-WorkOS.SSO.get_authorization_url(%{
-  connection: "<Connection ID>",
-  redirect_uri: "https://workos.com"
-}, [
-  client_id: "project_12345",
-  api_key: "sk_12345"
-])
-```
-This is great if you need to switch client IDs on the fly.
+###
 
 ## SDK Versioning
 
 For our SDKs WorkOS follows a Semantic Versioning process where all releases will have a version X.Y.Z (like 1.0.0) pattern wherein Z would be a bug fix (I.e. 1.0.1), Y would be a minor release (1.1.0) and X would be a major release (2.0.0). We permit any breaking changes to only be released in major versions and strongly recommend reading changelogs before making any major version upgrades.
 
 ## More Information
 
-* [Single Sign-On Guide](https://workos.com/docs/sso/guide)
-* [Directory Sync Guide](https://workos.com/docs/directory-sync/guide)
-* [Admin Portal Guide](https://workos.com/docs/admin-portal/guide)
-* [Magic Link Guide](https://workos.com/docs/magic-link/guide)
+- [User Management Guide](https://workos.com/docs/user-management)
+- [Single Sign-On Guide](https://workos.com/docs/sso/guide)
+- [Directory Sync Guide](https://workos.com/docs/directory-sync/guide)
+- [Admin Portal Guide](https://workos.com/docs/admin-portal/guide)
+- [Magic Link Guide](https://workos.com/docs/magic-link/guide)
+- [Domain Verification Guide](https://workos.com/docs/domain-verification/guide)

config/config.exs

@@ -0,0 +1,3 @@
+import Config
+
+import_config "#{Mix.env()}.exs"

config/dev.exs

@@ -0,0 +1,5 @@
+import Config
+
+config :workos, WorkOS.Client,
+  client_id: System.get_env("WORKOS_CLIENT_ID"),
+  api_key: System.get_env("WORKOS_API_KEY")

config/prod.exs

@@ -0,0 +1 @@
+# This empty module is for configuration purposes

config/test.exs

@@ -0,0 +1,16 @@
+import Config
+
+workos_api_key = System.get_env("WORKOS_API_KEY")
+workos_client_id = System.get_env("WORKOS_CLIENT_ID")
+
+case {workos_api_key, workos_client_id} do
+  {nil, nil} ->
+    config :tesla, adapter: Tesla.Mock
+
+    config :workos, WorkOS.Client,
+      api_key: "sk_example_123456789",
+      client_id: "client_123456789"
+
+  {api_key, client_id} ->
+    config :workos, WorkOS.Client, api_key: api_key, client_id: client_id
+end

lib/workos.ex

@@ -1,17 +1,123 @@
 defmodule WorkOS do
   @moduledoc """
-  Use the WorkOS module to authenticate your requests to the WorkOS API
+  Documentation for `WorkOS`.
   """
 
-  def host, do: Application.get_env(:workos, :host)
-  def base_url, do: "https://" <> Application.get_env(:workos, :host)
-  def adapter, do: Application.get_env(:workos, :adapter) || Tesla.Adapter.Hackney
+  @config_module WorkOS.Client
 
-  def api_key(opts \\ [])
-  def api_key(api_key: api_key), do: api_key
-  def api_key(_opts), do: Application.get_env(:workos, :api_key)
+  @type config() ::
+          list(
+            {:api_key, String.t()}
+            | {:client_id, String.t()}
+            | {:base_url, String.t()}
+            | {:client, atom()}
+          )
 
-  def client_id(opts \\ [])
-  def client_id(client_id: client_id), do: client_id
-  def client_id(_opts), do: Application.get_env(:workos, :client_id)
+  @doc """
+  Returns a WorkOS client.
+
+  Accepts a keyword list of config opts, though if omitted then it will attempt to load
+  them from the application environment.
+  """
+  @spec client() :: WorkOS.Client.t()
+  @spec client(config()) :: WorkOS.Client.t()
+  def client(config \\ config()) do
+    WorkOS.Client.new(config)
+  end
+
+  @doc """
+  Loads config values from the application environment.
+
+  Config options are as follows:
+
+  ```ex
+  config :workos, WorkOS.Client
+    api_key: "sk_123",
+    client_id: "project_123",
+    base_url: "https://api.workos.com",
+    client: WorkOs.Client.TeslaClient
+  ```
+
+  The only required config option is `:api_key` and `:client_id`. If you would like to replace the
+  HTTP client used by WorkOS, configure the `:client` option. By default, this library
+  uses [Tesla](https://github.com/elixir-tesla/tesla), but changing it is as easy as
+  defining your own client module. See the `WorkOS.Client` module docs for more info.
+  """
+  @spec config() :: config()
+  def config do
+    config =
+      Application.get_env(:workos, @config_module) ||
+        raise """
+        Missing client configuration for WorkOS.
+
+        Configure your WorkOS API key in one of your config files, for example:
+
+            config :workos, #{inspect(@config_module)}, api_key: "sk_123", client_id: "project_123"
+        """
+
+    validate_config!(config)
+  end
+
+  @spec validate_config!(WorkOS.config()) :: WorkOS.config() | no_return()
+  defp validate_config!(config) do
+    Keyword.get(config, :api_key) ||
+      raise WorkOS.ApiKeyMissingError
+
+    Keyword.get(config, :client_id) ||
+      raise WorkOS.ClientIdMissingError
+
+    config
+  end
+
+  @doc """
+  Defines the WorkOS base API URL
+  """
+  def default_base_url, do: "https://api.workos.com"
+
+  @doc """
+  Retrieves the WorkOS base URL from application config.
+  """
+  @spec base_url() :: String.t()
+  def base_url do
+    case Application.get_env(:workos, @config_module) do
+      config when is_list(config) ->
+        Keyword.get(config, :base_url, default_base_url())
+
+      _ ->
+        default_base_url()
+    end
+  end
+
+  @doc """
+  Retrieves the WorkOS client ID from application config.
+  """
+  @spec client_id() :: String.t()
+  def client_id do
+    case Application.get_env(:workos, @config_module) do
+      config when is_list(config) ->
+        Keyword.get(config, :client_id, nil)
+
+      _ ->
+        nil
+    end
+  end
+
+  @spec client_id(WorkOS.Client.t()) :: String.t()
+  def client_id(client) do
+    Map.get(client, :client_id)
+  end
+
+  @doc """
+  Retrieves the WorkOS API key from application config.
+  """
+  @spec api_key() :: String.t()
+  def api_key do
+    WorkOS.config()
+    |> Keyword.get(:api_key)
+  end
+
+  @spec api_key(WorkOS.Client.t()) :: String.t()
+  def api_key(client) do
+    Map.get(client, :api_key)
+  end
 end