feat: add documentation

supabase-community · Apr 16, 2024 · 87ec8ea · 87ec8ea
1 parent 1c664e6
commit 87ec8ea
Show file tree

Hide file tree

Showing 24 changed files with 463 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -1 +1,34 @@
-# Supabase Auth (GoTrue)
+# Supabase GoTrue
+
+[Auth](https://supabase.com/docs/guides/auth) implementation for the `supabase_potion` SDK in Elixir.
+
+## Installation
+
+```elixir
+def deps do
+  [
+    {:supabase_potion, "~> 0.3"},
+    {:supabase_gotrue, "~> 0.2"}
+  ]
+end
+```
+
+## Usage
+
+Firstly you need to initialize your Supabase client(s) as can be found on the [supabase_potion documentation](https://hexdocs.pm/supabase_potion/Supabase.html#module-starting-a-client):
+
+```elixir
+iex> Supabase.init_client(%{name: Conn, conn: %{base_url: "<supa-url>", api_key: "<supa-key>"}})
+{:ok, #PID<>}
+```
+
+Now you can pass the Client to the `Supabase.GoTrue` functions as a `PID` or the name that was registered on the client initialization:
+
+```elixir
+iex> Supabase.GoTrue.sign_in_with_password(pid | client_name, %{} = params)
+```
+
+This implementation also exposes an `Supaabse.GoTrue.Admin` function to interact with users with super powers:
+```elixir
+iex> Supabase.GoTrue.Admin.create_user(pid | client_name, %{} = params)
+```
diff --git a/lib/supabase/go_true.ex b/lib/supabase/go_true.ex
@@ -1,5 +1,14 @@
 defmodule Supabase.GoTrue do
-  @moduledoc false
+  @moduledoc """
+  This module provides the functionality to interact with the GoTrue API,
+  allowing management of users, sessions, and authentication.
+
+  It also aims to provide integrations with Plug and Phoenix LiveView applications.
+
+  For detailed information about the GoTrue API, check the official documentation at https://supabase.io/docs/reference/javascript/auth-api
+
+  And also refer to functions and submodules documentation for more information.
+  """
 
   import Supabase.Client, only: [is_client: 1]
 
@@ -18,6 +27,18 @@ defmodule Supabase.GoTrue do
 
   @behaviour Supabase.GoTrueBehaviour
 
+  @doc """
+  Get the user associated with the current session.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `session` - The session to use for the request. Check `Supabase.GoTrue.Session` for more information.
+
+  ## Examples
+      iex> session = %Supabase.GoTrue.Session{access_token: "example_token"}
+      iex> Supabase.GoTrue.get_user(pid | client_name, session)
+      {:ok, %Supabase.GoTrue.User{}}
+  """
   @impl true
   def get_user(client, %Session{} = session) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -26,6 +47,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs in a user with ID token.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign in. Check `Supabase.GoTrue.Schemas.SignInWithIdToken` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignInWithIdToken{}
+      iex> Supabase.GoTrue.sign_in_with_id_token(pid | client_name, credentials)
+      {:ok, %Supabase.GoTrue.User{}}
+  """
   @impl true
   def sign_in_with_id_token(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -34,6 +67,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs in a user with OAuth.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign in. Check `Supabase.GoTrue.Schemas.SignInWithOauth` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignInWithOauth{}
+      iex> Supabase.GoTrue.sign_in_with_oauth(pid | client_name, credentials)
+      {:ok, atom, URI.t()}
+  """
   @impl true
   def sign_in_with_oauth(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -43,6 +88,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs in a user with OTP.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign in. Check `Supabase.GoTrue.Schemas.SignInWithOTP` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignInWithOTP{}
+      iex> Supabase.GoTrue.sign_in_with_otp(pid | client_name, credentials)
+      {:ok, %Supabase.GoTrue.Session{}}
+  """
   @impl true
   def sign_in_with_otp(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -51,6 +108,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Verifies an OTP code.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `params` - The parameters to use for the verification. Check `Supabase.GoTrue.Schemas.VerifyOTP` for more information.
+
+  ## Examples
+      iex> params = %Supabase.GoTrue.VerifyOTP{}
+      iex> Supabase.GoTrue.verify_otp(pid | client_name, params)
+      {:ok, %Supabase.GoTrue.Session{}}
+  """
   @impl true
   def verify_otp(client, params) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -59,6 +128,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs in a user with SSO.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign in. Check `Supabase.GoTrue.Schemas.SignInWithSSO` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignInWithSSO{}
+      iex> Supabase.GoTrue.sign_in_with_sso(pid | client_name, credentials)
+      {:ok, %Supabase.GoTrue.User{}}
+  """
   @impl true
   def sign_in_with_sso(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -67,6 +148,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs in a user with email/phone and password.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign in. Check `Supabase.GoTrue.Schemas.SignInWithPassword` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignInWithPassword{}
+      iex> Supabase.GoTrue.sign_in_with_password(pid | client_name, credentials)
+      {:ok, %Supabase.GoTrue.Session{}}
+  """
   @impl true
   def sign_in_with_password(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -76,6 +169,18 @@ defmodule Supabase.GoTrue do
     end
   end
 
+  @doc """
+  Signs up a user with email/phone and password.
+
+  ## Parameters
+    - `client` - The `Supabase` client to use for the request.
+    - `credentials` - The credentials to use for the sign up. Check `Supabase.GoTrue.Schemas.SignUpWithPassword` for more information.
+
+  ## Examples
+      iex> credentials = %Supabase.GoTrue.SignUpWithPassword{}
+      iex> Supabase.GoTrue.sign_up(pid | client_name, credentials)
+      {:ok, %Supabase.GoTrue.User{}}
+  """
   @impl true
   def sign_up(client, credentials) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),

diff --git a/lib/supabase/go_true/admin.ex b/lib/supabase/go_true/admin.ex
@@ -1,5 +1,10 @@
 defmodule Supabase.GoTrue.Admin do
-  @moduledoc false
+  @moduledoc """
+  Admin module for GoTrue. This module provides functions to interact with the GoTrue admin API,
+  like signing out a user, inviting a user, and generating a link.
+
+  You can find more information about the GoTrue admin API at https://supabase.io/docs/reference/javascript/auth-admin-api
+  """
 
   import Supabase.Client, only: [is_client: 1]
 
@@ -17,6 +22,18 @@ defmodule Supabase.GoTrue.Admin do
 
   @scopes ~w[global local others]a
 
+  @doc """
+  Signs out a user from the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `session` - The session to sign out, often retrieved from a sign in function.
+    * `scope` - The scope to sign out the user from. Can be one of `global`, `local`, or `others`.
+
+  ## Examples
+      iex> session = %Session{access_token: "access_token"}
+      iex> Supabase.GoTrue.Admin.sign_out(pid | client_name, session, "global")
+  """
   @impl true
   def sign_out(client, %Session{} = session, scope) when is_client(client) and scope in @scopes do
     with {:ok, client} <- Client.retrieve_client(client) do
@@ -29,6 +46,17 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Invites a user to the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `email` - The email of the user to invite.
+    * `options` - The options to use for the invite. See `Supabase.GoTrue.Schemas.InviteUserParams` for more information.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.invite_user_by_email(pid | client_name, "[email protected]", %{})
+  """
   @impl true
   def invite_user_by_email(client, email, options \\ %{}) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -38,6 +66,16 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Generates a link for the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `attrs` - The attributes to use for the link. See `Supabase.GoTrue.Schemas.GenerateLink` for more information.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.generate_link(pid | client_name, %{})
+  """
   @impl true
   def generate_link(client, attrs) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -47,6 +85,16 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Creates a user in the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `attrs` - The attributes to use for the user. See `Supabase.GoTrue.Schemas.AdminUserParams` for more information.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.create_user(pid | client_name, %{})
+  """
   @impl true
   def create_user(client, attrs) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -56,6 +104,17 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Deletes a user in the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `user_id` - The ID of the user to delete.
+    * `opts` - Controls if the user should be soft deleted or not.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.update_user(pid | client_name, "user_id", %{})
+  """
   @impl true
   def delete_user(client, user_id, opts \\ [should_soft_delete: false]) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -64,6 +123,16 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Gets a user by ID in the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `user_id` - The ID of the user to get.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.get_user_by_id(pid | client_name, "user_id")
+  """
   @impl true
   def get_user_by_id(client, user_id) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -72,6 +141,16 @@ defmodule Supabase.GoTrue.Admin do
     end
   end
 
+  @doc """
+  Lists users in the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `params` - The parameters to use for the list. See `Supabase.GoTrue.Schemas.PaginationParams` for more information.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.list_users(pid | client_name, %{})
+  """
   @impl true
   def list_users(client, params \\ %{}) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),
@@ -115,6 +194,17 @@ defmodule Supabase.GoTrue.Admin do
     end)
   end
 
+  @doc """
+  Updates a user in the GoTrue admin API.
+
+  ## Parameters
+    * `client` - The `Supabase` client to use for the request.
+    * `user_id` - The ID of the user to update.
+    * `attrs` - The attributes to use for the user. See `Supabase.GoTrue.Schemas.AdminUserParams` for more information.
+
+  ## Examples
+      iex> Supabase.GoTrue.Admin.update_user(pid | client_name, "user_id", %{})
+  """
   @impl true
   def update_user_by_id(client, user_id, attrs) when is_client(client) do
     with {:ok, client} <- Client.retrieve_client(client),

diff --git a/lib/supabase/go_true/auth.ex b/lib/supabase/go_true/auth.ex
@@ -1,5 +1,7 @@
 defmodule Supabase.GoTrue.Auth do
-  @moduledoc false
+  @moduledoc """
+  This module contains the authentication logic for Supabase GoTrue.
+  """
 
   use Ecto.Schema
 

diff --git a/lib/supabase/go_true/pkce.ex b/lib/supabase/go_true/pkce.ex
@@ -1,5 +1,7 @@
 defmodule Supabase.GoTrue.PKCE do
-  @moduledoc false
+  @moduledoc """
+  This module is used to generate PKCE (Proof Key for Code Exchange) values.
+  """
 
   @verifier_length 56
 

diff --git a/lib/supabase/go_true/plug.ex b/lib/supabase/go_true/plug.ex
@@ -29,7 +29,7 @@ defmodule Supabase.GoTrue.Plug do
     |> configure_session(renew: true)
   end
 
-  def sig_in(%Conn{} = conn, client, attrs) when is_client(client) do
+  def sign_in(%Conn{} = conn, client, attrs) when is_client(client) do
     case maybe_sign_in(conn, client, attrs) do
       {:ok, session} -> put_session_token(conn, session.access_token)
       _ -> conn