npm package: @matchi/auth
Description: Client package for authentication in MATCHi
Latest version: 1.0.3

# @matchi/auth

Client package for authentication in MATCHi.

## Introduction

This is the MATCHi Authentication client for frontend applications, aiming to create a common set of functions to handle authentication through the system authentication provider .

Currently supported are **React Native** applications build with **Expo**. Support for React and NextJS web applications is planned.

## Installation

```
npm install @matchi/auth # using npm
bun install @matchi/auth # using bun
yarn add @matchi/auth # using yarn
```

## Getting started

You should wrap your application using the `AuthenticationProvider` and configure the options with your application `realm`, `clientId` and `redirectUri` configuration.

```tsx
import { useAuthentication, AuthenticationProvider } from "@matchi/auth";
import { OpenAPI } from "@matchi/api";

// Wrap your application with the configured provider
<AuthenticationProvider options={...}>
  <App />
</AuthenticationProvider>

// Use the hook to access methods and props in components
const { login, token } = useAuthentication();

// Your application should trigger the actions when needed
useEffect(() => {
  login().then(() => {
    console.log("You are logged in!")
  });
}, []);

// Watch the token and configure services when it changes
useEffect(() => {
  OpenAPI.TOKEN = token;
}, [token])
```

## States

The following states are possible in the module, with `Unavailable` as the default state while being instanced and `Unauthenticated` as the default passive state when authentication is ready to be used:

```typescript
import { AuthenticationStates } from "@matchi/auth";
const { state } = useAuthentication();

// Not ready yet and user cannot login or signup
AuthenticationStates.Unavailable;
// User is authenticated and can logout
AuthenticationStates.Authenticated;
// User is currently being authenticated (logged in)
AuthenticationStates.Authenticating;
// User is not authenticated and can login or signup
AuthenticationStates.Unauthenticated;
// User is currently being unauthenticated (logged out)
AuthenticationStates.Unauthenticating;
// Network error occurred - tokens are preserved for retry when connectivity is restored
AuthenticationStates.NetworkError;
```

### Network Error Handling

When a `NetworkError` state occurs, the authentication module **preserves existing tokens** in both state and secure storage. This allows users to retry authentication or continue using the app when network connectivity is restored. Network errors are considered temporary issues and do not invalidate the user's authentication status.

In contrast, the `Unauthenticated` state explicitly clears all tokens from storage, as it indicates that authentication has failed or the session has expired.

## Errors

The following errors are possible in the module, which are thrown by rejected promises resulting from the `login()`, `logout()`, or `signup()` methods.

```typescript
import { AuthenticationErrors } from "@matchi/auth";

// Server couldn't verify the request code sent by the client
AuthenticationErrors.UnverifiedRequestCode;
// Client couldn't identify the response code sent by the server
AuthenticationErrors.UnidentifiedResponseCode;
// There was no server response from the client request
AuthenticationErrors.MissingRequestResponse;
// There was no server discovery document found
AuthenticationErrors.MissingDiscoveryDocument;
```

## Storage

Tokens are saved in [SecureStore](https://docs.expo.dev/versions/latest/sdk/securestore/) in native applications and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) in web applications. If either of these are unsupported on the device, an error will be thrown.