# BkperAuth

OAuth authentication client for the Bkper API.

Provides framework-agnostic authentication with callback-based event handling.
Access tokens are stored in-memory; sessions persist via HTTP-only cookies.

## Example

```typescript
// Initialize authentication client
const auth = new BkperAuth({
  onLoginSuccess: () => loadUserData(),
  onLoginRequired: () => showLoginButton()
});

// Restore session on app load
await auth.init();
```

### Constructor

```ts
new BkperAuth(config?): BkperAuth;
```

Creates a new BkperAuth instance.

#### Parameters

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `config?` | [`BkperAuthConfig`](https://bkper.com/docs/api/bkper-web-auth/interfaces/bkperauthconfig.md) | Optional configuration for the auth client |

#### Returns

`BkperAuth`

#### Example

```typescript
// Simple usage with defaults
const auth = new BkperAuth();

// With callbacks
const auth = new BkperAuth({
  onLoginSuccess: () => console.log('Logged in!'),
  onLoginRequired: () => showLoginDialog(),
  onError: (error) => console.error(error)
});
```

### authenticatedFetch()

```ts
authenticatedFetch(input, init?): Promise;
```

Performs an authenticated request and retries it once after refreshing an
expired or invalid access token.

Concurrent refresh calls share the same refresh request. A second 401
response is returned without another retry.

Call `init()` before the first request. Bearer tokens are sent only to
HTTPS Bkper origins or the current local development origin. Request
paths are not restricted.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `input` | `RequestInfo` \| `URL` |
| `init?` | `RequestInit` |

#### Returns

`Promise`\<`Response`\>

***

### getAccessToken()

```ts
getAccessToken(): string | undefined;
```

Gets the current access token.

#### Returns

`string` \| `undefined`

The access token if authenticated, undefined otherwise

Use `authenticatedFetch()` for Fetch API requests. This getter is
available for HTTP clients that accept an access-token provider.

#### Example

```typescript
const tokenProvider = async () => auth.getAccessToken();
```

***

### init()

```ts
init(): Promise<void>;
```

Initializes the authentication state by attempting to refresh the access token.

Call this method when your app loads to restore the user's session.
Triggers `onLoginSuccess` if a valid session exists, or `onLoginRequired` if login is needed.

#### Returns

`Promise`\<`void`\>

***

### login()

```ts
login(): void;
```

Redirects the user to the login page.

The user will be redirected to the authentication service to complete the login flow.
After successful login, they will be redirected back to the current page.

#### Returns

`void`

#### Example

```typescript
// Trigger login when user clicks a button
loginButton.addEventListener('click', () => {
  auth.login();
});
```

***

### logout()

```ts
logout(): void;
```

Logs out the user and redirects to the logout page.

Triggers the `onLogout` callback before redirecting.
The user's session will be terminated.

#### Returns

`void`

#### Example

```typescript
// Logout when user clicks logout button
logoutButton.addEventListener('click', () => {
  auth.logout();
});
```

***

### refresh()

```ts
refresh(): Promise<void>;
```

Refreshes the access token using the current session.

Concurrent calls share one refresh request. Triggers `onTokenRefresh`
if successful and throws if the refresh request fails.

`authenticatedFetch()` calls this method automatically after a 401.
Consumers can also call it explicitly when they need a new token.

#### Returns

`Promise`\<`void`\>

#### Example

```typescript
await auth.refresh();
const token = auth.getAccessToken();
```