# `Sigra.Identity`
[🔗](https://github.com/sztheory/sigra/blob/v1.20.0/lib/sigra/identity.ex#L1)

Library struct representing an OAuth identity (provider account linked to a user).

Maps to and from the generated `UserIdentity` Ecto schema in the host app.
Contains all D-25 fields: provider info, encrypted tokens, profile data, and metadata.

## Fields

- `:id` - Database primary key
- `:user_id` - The owning user's ID
- `:provider` - Provider name as lowercase string (e.g., "google", "github")
- `:provider_uid` - Unique identifier from the provider
- `:encrypted_access_token` - Encrypted OAuth access token
- `:encrypted_refresh_token` - Encrypted OAuth refresh token
- `:token_expires_at` - When the access token expires
- `:provider_email` - Email from the provider (may differ from user's primary email)
- `:provider_name` - Display name from the provider
- `:provider_avatar_url` - Avatar URL from the provider
- `:metadata` - Normalized subset of provider response (locale, verified_email, etc.)
- `:last_used_at` - Last OAuth login or token refresh
- `:inserted_at` - Record creation timestamp
- `:updated_at` - Record update timestamp

# `t`

```elixir
@type t() :: %Sigra.Identity{
  encrypted_access_token: binary() | nil,
  encrypted_refresh_token: binary() | nil,
  id: term(),
  inserted_at: DateTime.t() | nil,
  last_used_at: DateTime.t() | nil,
  metadata: map(),
  provider: String.t() | nil,
  provider_avatar_url: String.t() | nil,
  provider_email: String.t() | nil,
  provider_name: String.t() | nil,
  provider_uid: String.t() | nil,
  token_expires_at: DateTime.t() | nil,
  updated_at: DateTime.t() | nil,
  user_id: term()
}
```

# `from_schema`
*since 0.1.0* 

```elixir
@spec from_schema(map()) :: t()
```

Creates an `Identity` struct from an Ecto schema struct or map.

Maps fields by name from the source to the Identity struct.
Unknown fields in the source are ignored.

## Examples

    iex> Sigra.Identity.from_schema(%{provider: "google", provider_uid: "123"})
    %Sigra.Identity{provider: "google", provider_uid: "123", metadata: %{}}

# `to_params`
*since 0.1.0* 

```elixir
@spec to_params(t()) :: map()
```

Converts an `Identity` struct to a map suitable for Ecto changeset params.

Normalizes the provider name to lowercase (D-30), drops `:id`, `:inserted_at`,
and `:updated_at` (managed by Ecto), and removes nil values.

## Examples

    iex> identity = %Sigra.Identity{provider: "Google", provider_uid: "123"}
    iex> Sigra.Identity.to_params(identity)
    %{provider: "google", provider_uid: "123", metadata: %{}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*