major refactor on documenation and client initialisation

Author: zoedsoupe

README.md

@@ -2,6 +2,9 @@
 
 Where the magic starts!
 
+> [!WARNING]
+> This project is still in high development, expect breaking changes.
+
 ## Getting Started
 
 ### Installation
@@ -11,7 +14,28 @@ To install the base SDK:
 ```elixir
 def deps do
   [
-    {:supabase_potion, "~> 0.4"}
+    {:supabase_potion, "~> 0.5"}
+  ]
+end
+```
+
+### General installation
+
+This library per si is the base foundation to user Supabase services from Elixir, so to integrate with specific services you need to add each client library you want to use.
+
+Available client services are:
+- [PostgREST](https://github.com/zoedsoupe/postgres-ex)
+- [Storage](https://github.com/zoedsoupe/storage-ex)
+- [Auth/GoTrue](https://github.com/zoedsoupe/gotrue-ex)
+
+So if you wanna use the Storage and Auth/GoTrue services, your `mix.exs` should look like that:
+
+```elixir
+def deps do
+  [
+    {:supabase_potion, "~> 0.5"}, # base SDK
+    {:supabase_storage, "~> 0.3"}, # storage integration
+    {:supabase_gotrue, "~> 0.3"}, # auth integration
   ]
 end
 ```
@@ -39,33 +63,90 @@ A `Supabase.Client` holds general information about Supabase, that can be used t
     - `:storage` - storage type
     - `:storage_key` - storage key
 
-## Configuration
+### Usage
+
+There are two ways to create a `Supabase.Client`:
+1. one off clients
+2. self managed clients
+
+#### One off clients
+
+One off clients are clients that are created and managed by your application. They are useful for quick interactions with the Supabase API.
+
+```elixir
+iex> Supabase.init_client("https://<supabase-url>", "<supabase-api-key>")
+iex> {:ok, %Supabase.Client{}}
+```
+
+Any additional config can be passed as the third argument:
+
+```elixir
+iex> Supabase.init_client("https://<supabase-url>", "<supabase-api-key>", %{db: %{schema: "another"}}})
+iex> {:ok, %Supabase.Client{}}
+```
+
+For more information on the available options, see the [Supabase.Client](https://hexdocs.pm/supabase_potion/Supabase.Client.html) module documentation.
+
+> There's also a bang version of `Supabase.init_client/3` that will raise an error if the client can't be created.
+
+#### Self managed clients
+
+Self managed clients are clients that are created and managed by a separate process on your application. They are useful for long running applications that need to interact with the Supabase API.
+
+If you don't have experience with processes or is a Elixir begginner, you should take a deep look into the Elixir official getting started section about processes, concurrency and distribution before to proceed.
+- [Processes](https://hexdocs.pm/elixir/processes.html)
+- [Agent getting started](https://hexdocs.pm/elixir/agents.html)
+- [GenServer getting started](https://hexdocs.pm/elixir/genservers.html)
+- [Supervison trees getting started](https://hexdocs.pm/elixir/supervisor-and-application.html)
 
-Ensure your Supabase configurations are set:
+So, to define a self managed client, you need to define a module that will hold the client state and the client process.
+
+```elixir
+defmodule MyApp.Supabase.Client do
+  use Supabase.Client
+end
+```
+
+For that to work, you also need to configure the client in your `config.exs`:
 
 ```elixir
 import Config
 
-config :supabase,
-  supabase_base_url: System.fetch_env!("SUPABASE_BASE_URL"),
-  supabase_api_key: System.fetch_env!("SUPABASE_API_KEY"),
+config :supabase_potion, MyApp.Supabase.Client,
+  base_url: "https://<supabase-url>", # required
+  api_key: "<supabase-api-key>", # required
+  conn: %{access_token: "<supabase-token>"}, # optional
+  db: %{schema: "another"} # additional options
 ```
 
-- `supabase_base_url`: The base URL of your Supabase project! More information on how to find it can be seen on the [next section](#how-to-find-my-supabase-base-url?)
-- `supabase_api_key`: The secret of your Supabase project! More information on how to find it can be seen on the [next section](#how-to-find-my-supabase-api-key?)
+Then, you can start the client process in your application supervision tree:
 
-Make sure to set the environment variables `SUPABASE_BASE_URL` and `SUPABASE_API_KEY`.
+```elixir
+defmodule MyApp.Application do
+  use Application
+
+  def start(_type, _args) do
+    children = [
+      MyApp.Supabase.Client
+    ]
 
-## Starting a Client
+    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end
+```
 
-You can start a client using the `Supabase.init_client/1` or `Supabase.init_client!/1` function.
+Now you can interact with the client process:
 
 ```elixir
-iex> Supabase.init_client!(%{conn: %{base_url: "<supa-url>", api_key: "<supa-key>"}})
-{:ok, %Supabase.Client{}}
+iex> {:ok, %Supabase.Client{} = client} = MyApp.Supabase.Client.get_client()
+iex> Supabase.GoTrue.sign_in_with_password(client, email: "", password: "")
 ```
 
-> Note that if you already set up supabase potion options on your application config, you can safely use `Supabase.init_client/0` or `Supabase.init_client!/0`
+For more examples on how to use the client, check clients implementations docs:
+- [Supabase.GoTrue](https://hexdocs.pm/supabase_go_true)
+- [Supabase.Storage](https://hexdocs.pm/supabase_storage)
+- [Supabase.PostgREST](https://hexdocs.pm/supabase_postgrest)
 
 ### How to find my Supabase base URL?
 

config/config.exs

@@ -2,71 +2,23 @@ defmodule Supabase do
   @moduledoc """
   The main entrypoint for the Supabase SDK library.
 
-  ## Installation
-
-  The package can be installed by adding `supabase_potion` to your list of dependencies in `mix.exs`:
-
-      def deps do
-        [
-          {:supabase_potion, "~> 0.3"}
-        ]
-      end
-
-  ## Usage
-
-  After installing `:supabase_potion`, you can easily and dynamically manage different `Supabase.Client`!
-
-  ### Config
-
-  The library offers a bunch of config options that can be used to control management of clients and other options.
-
-  - `manage_clients` - whether to manage clients automatically, defaults to `true`
-
-  You can set up the library on your `config.exs`:
-
-      config :supabase, manage_clients: false
-
-  ### Clients
-
-  A `Supabase.Client`  holds general information about Supabase, that can be used to intereact with any of the children integrations, for example: `Supabase.Storage` or `Supabase.UI`.
-
-  `Supabase.Client` is defined as:
-
-  - `:conn` - connection information, the only required option as it is vital to the `Supabase.Client`.
-    - `:base_url` - The base url of the Supabase API, it is usually in the form `https://<app-name>.supabase.co`.
-    - `:api_key` - The API key used to authenticate requests to the Supabase API.
-    - `:access_token` - Token with specific permissions to access the Supabase API, it is usually the same as the API key.
-  - `:db` - default database options
-    - `:schema` - default schema to use, defaults to `"public"`
-  - `:global` - global options config
-    - `:headers` - additional headers to use on each request
-  - `:auth` - authentication options
-    - `:auto_refresh_token` - automatically refresh the token when it expires, defaults to `true`
-    - `:debug` - enable debug mode, defaults to `false`
-    - `:detect_session_in_url` - detect session in URL, defaults to `true`
-    - `:flow_type` - authentication flow type, defaults to `"web"`
-    - `:persist_session` - persist session, defaults to `true`
-    - `:storage` - storage type
-    - `:storage_key` - storage key
-
-
   ## Starting a Client
 
-  You then can start a Client calling `Supabase.init_client/1`:
+  You then can start a Client calling `Supabase.init_client/3`:
 
-      iex> Supabase.init_client(%{db: %{schema: "public"}})
+      iex> Supabase.init_client("base_url", "api_key", %{db: %{schema: "public"}})
       {:ok, %Supabase.Client{}}
 
   ## Acknowledgements
 
   This package represents the base SDK for Supabase. That means
   that it not includes all of the functionality of the Supabase client integrations, so you need to install each feature separetely, as:
 
-  - [auth](https://github.com/zoedsoupe/gotrue-ex)
-  - [storage](https://github.com/zoedsoupe/storage-ex)
-  - [postgrest](https://github.com/zoedsoupe/postgrest-ex)
-  - `realtime` - TODO
-  - `ui` - TODO
+  - [Auth/GoTrue](https://github.com/zoedsoupe/gotrue-ex)
+  - [Storage](https://github.com/zoedsoupe/storage-ex)
+  - [PostgREST](https://github.com/zoedsoupe/postgrest-ex)
+  - `Realtime` - TODO
+  - `UI` - TODO
 
   ### Supabase Storage
 
@@ -80,7 +32,7 @@ defmodule Supabase do
 
   Supabase Realtime provides a realtime websocket API powered by PostgreSQL notifications. It allows you to listen to changes in your database, and instantly receive updates as soon as they happen.
 
-  ### Supabase Auth
+  ### Supabase Auth/GoTrue
 
   Supabase Auth is a feature-complete user authentication system. It provides email & password sign in, email verification, password recovery, session management, and more, out of the box.
 
@@ -95,46 +47,37 @@ defmodule Supabase do
 
   @typep changeset :: Ecto.Changeset.t()
 
-  @spec init_client(Client.params() | %{}) :: {:ok, Client.t()} | {:error, changeset}
-  def init_client(opts \\ %{}) do
+  @spec init_client(String.t(), String.t(), Client.params() | %{}) :: {:ok, Client.t()} | {:error, changeset}
+  def init_client(url, api_key, opts \\ %{})
+    when is_binary(url) and is_binary(api_key) do
     opts
-    |> Map.get(:conn, %{})
-    |> maybe_merge_config_from_application(opts)
+    |> Map.put(:conn, %{base_url: url, api_key: api_key})
+    |> Map.update(:conn, opts, &Map.merge(&1, opts[:conn]))
     |> Client.parse()
   end
 
-  def init_client!(%{} = opts \\ %{}) do
-    conn = Map.get(opts, :conn, %{})
-    opts = maybe_merge_config_from_application(conn, opts)
-
-    case init_client(opts) do
+  @spec init_client!(String.t, String.t, Client.params | %{}) :: Client.t() | no_return
+  def init_client!(url, api_key, %{} = opts \\ %{})
+    when is_binary(url) and is_binary(api_key) do
+    case init_client(url, api_key, opts) do
       {:ok, client} ->
         client
 
       {:error, changeset} ->
         errors = errors_on_changeset(changeset)
 
-        if "can't be blank" in get_in(errors, [:conn, :api_key]) do
-          raise MissingSupabaseConfig, :key
+        if "can't be blank" in (get_in(errors, [:conn, :api_key]) || []) do
+          raise MissingSupabaseConfig, key: :key, client: nil
         end
 
-        if "can't be blank" in get_in(errors, [:conn, :base_url]) do
-          raise MissingSupabaseConfig, :url
+        if "can't be blank" in (get_in(errors, [:conn, :base_url]) || []) do
+          raise MissingSupabaseConfig, key: :url, client: nil
         end
 
         raise Ecto.InvalidChangesetError, changeset: changeset, action: :init
     end
   end
 
-  defp maybe_merge_config_from_application(%{base_url: _, api_key: _}, opts), do: opts
-
-  defp maybe_merge_config_from_application(%{}, opts) do
-    base_url = Application.get_env(:supabase_potion, :supabase_base_url)
-    api_key = Application.get_env(:supabase_potion, :supabase_api_key)
-
-    Map.put(opts, :conn, %{base_url: base_url, api_key: api_key})
-  end
-
   defp errors_on_changeset(changeset) do
     Ecto.Changeset.traverse_errors(changeset, fn {message, opts} ->
       Regex.replace(~r"%{(\w+)}", message, fn _, key ->