# `Pluggy.Session`
[🔗](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/session.ex#L1)

A plain struct with functional API for managing a Pluggy connection session.

A session holds a client, an optional connect token, and the connected item data.
State lives in the caller's process (LiveView socket, Livebook cell, etc.) —
no GenServer is used.

## Usage

    {:ok, client} = Pluggy.Client.new("client_id", "client_secret")
    session = Pluggy.Session.new(client)

    # Get a connect token for the widget
    {:ok, token, session} = Pluggy.Session.connect_token(session)

    # After widget connection completes
    session = Pluggy.Session.with_item(session, item_data)

    # Fetch resources
    {:ok, accounts} = Pluggy.Session.accounts(session)
    {:ok, txns} = Pluggy.Session.transactions(session, account_id)

# `t`

```elixir
@type t() :: %Pluggy.Session{
  client: Pluggy.Client.t(),
  connect_token: String.t() | nil,
  connect_token_opts: keyword(),
  item: map() | nil,
  item_id: String.t() | nil
}
```

# `accounts`

```elixir
@spec accounts(
  t(),
  keyword()
) :: {:ok, term()} | {:error, Pluggy.Error.t() | :no_item}
```

Fetches accounts for the connected item.

Returns `{:error, :no_item}` if no item has been set.

# `client`

```elixir
@spec client(t()) :: Pluggy.Client.t()
```

Returns the underlying `Pluggy.Client` for direct API calls.

# `connect_token`

```elixir
@spec connect_token(t()) :: {:ok, String.t(), t()} | {:error, Pluggy.Error.t()}
```

Fetches a connect token for this session.

Returns `{:ok, token, updated_session}` where the updated session caches the token.
If a token is already cached, returns it without making a new request.

# `identity`

```elixir
@spec identity(
  t(),
  keyword()
) :: {:ok, term()} | {:error, Pluggy.Error.t() | :no_item}
```

Fetches identity data for the connected item.

# `investments`

```elixir
@spec investments(
  t(),
  keyword()
) :: {:ok, term()} | {:error, Pluggy.Error.t() | :no_item}
```

Fetches investments for the connected item.

# `loans`

```elixir
@spec loans(
  t(),
  keyword()
) :: {:ok, term()} | {:error, Pluggy.Error.t() | :no_item}
```

Fetches loans for the connected item.

# `new`

```elixir
@spec new(
  Pluggy.Client.t(),
  keyword()
) :: t()
```

Creates a new session from a `Pluggy.Client`.

## Options

  * `:webhook_url` - URL for webhook notifications (passed as connect token option)
  * Any other options are stored and passed when creating connect tokens.

# `refresh_connect_token`

```elixir
@spec refresh_connect_token(t()) ::
  {:ok, String.t(), t()} | {:error, Pluggy.Error.t()}
```

Refreshes the connect token, ignoring any cached value.

# `transactions`

```elixir
@spec transactions(t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, Pluggy.Error.t() | :no_item}
```

Fetches transactions for a given account ID.

Returns `{:error, :no_item}` if no item has been set.

# `with_item`

```elixir
@spec with_item(t(), map()) :: t()
```

Sets the connected item data on the session.

The `item_data` map should contain the item information returned by the
Pluggy Connect widget's `onSuccess` callback.

---

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