# Internal Hooks

**⚠️ Internal SDK Infrastructure - Not Exported**

These hooks are used internally by the Deva SDK to manage authentication, notifications, and session persistence. They are **not exported** from the package and cannot be imported by external applications.

***

## Overview

The SDK uses several internal hooks to power its core functionality:

| Hook                         | Purpose             | Used By             |
| ---------------------------- | ------------------- | ------------------- |
| `useStorage`                 | Session persistence | DevaProvider        |
| `useToast`                   | Notification system | Login flow, Toaster |
| `useTimeout` / `useInterval` | Timer management    | Token refresh       |

**Note:** Only `useDeva` is part of the public API. These internal hooks are documented here for transparency about how the SDK works internally.

***

## useStorage

**Purpose:** Persists authentication state using browser sessionStorage.

**What it does:**

* Wraps React state with automatic sessionStorage persistence
* Stores authentication tokens across page refreshes
* Type-safe with TypeScript generics
* SSR-compatible (checks for browser environment)
* Handles JSON serialization/deserialization

**Used by DevaProvider to store:**

* Access tokens
* Refresh tokens
* ID tokens
* Token expiration times
* PKCE code verifier (during OAuth flow)
* Authentication progress flags

**Why not exported:**

* Authentication state is managed automatically by DevaProvider
* Applications access state through `useDeva` hook
* Direct sessionStorage manipulation would break SDK's auth flow
* Session persistence should be transparent to applications

**Implementation:** `src/hooks/use-storage.ts`

***

## useToast

**Purpose:** Manages toast notification state and display logic.

**What it does:**

* Global state manager for toast notifications
* Uses reducer pattern (ADD, UPDATE, DISMISS, REMOVE actions)
* Maintains in-memory state with React listeners
* Limits to 1 toast displayed at a time
* Handles toast lifecycle (create, update, dismiss)

**Used by:**

* **Login component** - Shows success/failure notifications during authentication
* **Toaster component** - Renders active toasts to the UI

**Notification types:**

* `default` - Standard notifications (login success)
* `destructive` - Error notifications (login failure)

**Why not exported:**

* SDK handles notifications automatically during auth flows
* Applications can use the exported `<Toaster />` component
* Direct toast control is not part of the public API surface
* Notification system is internal infrastructure

**Implementation:** `src/hooks/use-toast.ts`

***

## useTimeout / useInterval

**Purpose:** Manages timers for automatic token refresh.

**What they do:**

* `useTimeout` - Executes callback once after delay
* `useInterval` - Executes callback repeatedly at interval
* Properly cleans up timers on unmount
* Stores callback in ref to avoid stale closures
* SSR-compatible using `useIsomorphicLayoutEffect`

**Used by DevaProvider for:**

* **Token refresh interval** - Checks token expiration every \~1 second (with random stagger)
* **Automatic token refresh** - Refreshes tokens before expiration
* **Background monitoring** - Continuous auth state validation

**Why not exported:**

* Token refresh is handled automatically by the SDK
* Applications don't need to manage timers for auth
* Internal timing logic for SDK reliability
* Timer management is infrastructure concern

**Implementation:** `src/hooks/use-timeout.ts`

***

## How They Work Together

**Authentication Flow:**

1. **Login initiated** → `useStorage` clears previous state
2. **OAuth redirect** → `useStorage` stores PKCE verifier
3. **Token received** → `useStorage` persists tokens to sessionStorage
4. **Success notification** → `useToast` displays login success message
5. **Token monitoring** → `useInterval` checks expiration every \~1 second
6. **Token refresh** → `useStorage` updates with new tokens
7. **Page refresh** → `useStorage` restores session from sessionStorage

**User Experience:**

* Tokens automatically refresh in background (useInterval)
* Session persists across page refreshes (useStorage)
* Users see authentication feedback (useToast)
* All managed transparently by DevaProvider

***

## Related Documentation

* [useDeva Hook](/hooks-api/use-deva.md) - Public API for authentication
* [DevaProvider](/api-reference/deva-provider.md) - Provider configuration
* [Architecture Overview](/core-concepts/architecture-overview.md) - SDK structure
* [Session Persistence](/authentication/session-persistence.md) - How sessions persist
* [Token Management](/authentication/token-management.md) - Token lifecycle


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdkdocs.deva.me/hooks-api/internal-hooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.