svix-react/README.md

React components for using Svix in your dashboard.

# Svix React

## Installation

```sh
yarn add svix-react svix
# or
npm i svix-react svix
```

## App Portal usage

```ts
import React from "react";
import ReactDOM from "react-dom";
import { AppPortal } from "svix-react";

import "svix-react/style.css";

const SvixEmbed = () => {
  const svixAppId = 'app_x'; // this might vary from customer to customer

  const [appPortal, setAppPortal] = React.useState(null);
  const svixAppPortal = React.useEffect(() => {
    // Prerequisite: You'll need an endpoint that returns the App Portal
    // magic URL (https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access)
    fetch(`/your-backend-service/svix/${svixAppId}/app-portal`, { method: "POST" })
      .then(res => res.json())
      .then(result => setAppPortal(result));
  }, [svixAppId]);

  return (
    <AppPortal url={appPortal?.url} />
  );
};

const App = () => (
  <SvixEmbed />
);

ReactDOM.render(<App />, document.body);
```

### Self-sizing iframe
If you need `<AppPortal />` to adjust its height based on its content (e.g. to remove scrollbars), you can pass the `fullSize` prop like this:

```jsx
<AppPortal fullSize />
```

## React Hooks
This library also provides some custom hooks that can be helpful when implementing a custom App Portal.

### `SvixProvider`
To use the hooks, you must wrap your app inside the SvixProvider component:

```jsx
function MyApp() {
  <SvixProvider
    token={token}
    appId={appId}
  >
    {/* Your app's components */}
  </SvixProvider>
}
```
The `token` is returned by the App Portal access endpoint ([docs](https://api.svix.com/docs#tag/Authentication/operation/v1.authentication.app-portal-access)). You will need a backend endpoint in your service that calls this endpoint and returns the `token`.
**This is not your Svix API key**.

Svix hooks *must* be called from within the provider's hierarchy. You can also optionally pass a `SvixOptions` object via the `options` property.

### Example usage

```jsx
import { useEndpoints } from 'svix-react'

function ListEndpoints() {
  const endpoints = useEndpoints()

  return (
    <div>
      {endpoints.error && <div>An error has occurred</div>}
      {endpoints.loading && <div>Loading...</div>}
      <ul>
        {endpoints.data?.map((endpoint) => (
          <li>{endpoint.url}</li>
        ))}
      </ul>
      <button disabled={!endpoints.hasPrevPage} onClick={endpoints.prevPage}>
        Previous Page
      </button>
      <button disabled={!endpoints.hasNextPage} onClick={endpoints.nextPage}>
        Next Page
      </button>
    </div>
  )
}
```

### Common types
You'll see most of the hooks accept and return these standardized types.

#### `SvixPaginatedData<T>`
An object that allows for easy iteration over large sets of data. The type returned by *list* hooks.

```typescript
export interface SvixPaginatedData<T> {
  data: T[] | undefined;
  reload: () => void;
  hasPrevPage: boolean;
  hasNextPage: boolean;
  prevPage: () => void;
  nextPage: () => void;
  loading: boolean;
  error: Error | undefined;
  iterator: Iterator;
}
```

#### `SvixPaginatedOptions`
An object for controlling iteration over large sets of data
```typescript
export interface SvixPaginatedOptions {
  limit?: number;
  iterator?: Iterator;
}
```

#### `SvixEntity`
An object for interacting with a Svix entity. The type returned by the hooks that return a single entity.

```typescript
interface SvixEntity<T> {
  data: T | undefined;
  reload: () => void;
  loading: boolean;
  error: Error | undefined;
}
```

### Available hooks
Note: these hooks must be used within the `SvixProvider` context.

#### `useSvix`
Returns the [Svix library](https://github.com/svix/svix-webhooks/tree/main/javascript) and the active app ID.

```typescript
function useSvix(): {
  svix: Svix,
  appId: string
}
```

#### `useEndpoints`
List the application's endpoints ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.list)).

```typescript
function useEndpoints(options?: SvixPaginatedOptions): SvixPaginatedData<EndpointOut>
```

#### `useEndpoint`
Get an endpoint ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.get)).

```typescript
function useEndpoint(endpointId: string): SvixEntity<EndpointOut>
```

#### `useEndpointMessageAttempts`
List message atttempts by endpoint id ([docs](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.list-by-endpoint)).

```typescript
function useEndpointMessageAttempts(endpointId: string, options?: SvixPaginatedOptionsAttempts): SvixPaginatedData<MessageAttemptOut>
```

#### `useAttemptedMessages`
List messages for a particular endpoint ([docs](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.list-attempted-messages)). Additionally includes metadata about the latest message attempt.

```typescript
function useAttemptedMessages(endpointId: string, options?: SvixPaginatedOptionsAttempts):
SvixPaginatedData<EndpointMessageOut>
```

#### `useEndpointSecret`
Get the endpoint's signing secret ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.get-secret)).

```typescript
function useEndpointSecret(endpointId: string): {
  rotateSecret: (newSecret: EndpointSecretRotateIn) => Promise<void>
} extends SvixEntity<EndpointSecretOut>
```

#### `useEndpointHeaders`
Get the additional headers to be sent with the webhook ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.get-headers)).

```typescript
function useEndpointHeaders(endpointId: string): {
  updateEndpointHeaders: (headers: EndpointHeadersIn) => Promise<void>,
  patchHeaders: (headers: EndpointHeadersPatchIn) => Promise<void>
} extends SvixEntity<EndpointHeadersOut>
```

#### `useEndpointFunctions`
Utility methods to act on a specific endpoint.

- [`updateEndpoint` docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.update)
- [`deleteEndpoint` docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.delete)
- `recoverEndpointMessages`: Resend all failed messages since a given time ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.recover))

```typescript
function useEndpointFunctions(endpointId: string): {
  recoverEndpointMessages: (options: RecoverIn) => Promise<void>,
  updateEndpoint: (options: EndpointUpdate) => Promise<EndpointOut>,
  deleteEndpoint: () => Promise<void>
}
```

#### `useEndpointStats`
Get basic statistics for the endpoint ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.get-stats))

```typescript
function useEndpointStats(endpointId: string): SvixEntity<EndpointStats>
```

#### `useNewEndpoint`
Provides form state and other useful utilities for creating a new endpoint ([docs](https://api.svix.com/docs#tag/Endpoint/operation/v1.endpoint.create)).

```typescript
function useNewEndpoint(): {
  url: SvixField<string>,
  description: SvixField<string>,
  eventTypes: SvixField<string[]>,
  rateLimitPerSecond: SvixField<number | undefined>,
  createEndpoint: () => Promise<{ endpoint: EndpointOut, error: Error }>
}

interface SvixField<T> {
  value: T;
  setValue: (v: T) => void;
}
```
Call `setValue` on the endpoint fields before calling `createEndpoint`.

#### `useEventTypes`
List the available event types ([docs](https://api.svix.com/docs#tag/Event-Type/operation/v1.event-type.list))

```typescript
function useEventTypes(options?: SvixPaginatedOptions): SvixPaginatedData<EventTypeOut>
```

#### `useMessages`
List the application's messages. Messages are the webhook events being sent ([docs](https://api.svix.com/docs#tag/Message/operation/v1.message.list)).

```typescript
function useMessages(options?: SvixPaginatedOptionsMessages): SvixPaginatedData<MessageOut>
```

#### `useMessage`
Get a message by its ID or eventID ([docs](https://api.svix.com/docs#tag/Message/operation/v1.message.get)).

```typescript
function useMessage(messageId: string): SvixEntity<MessageOut>
```

#### `useMessageEndpoints`
List endpoints attempted by a given message ([docs](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.list-attempted-destinations)).

```typescript
function (messageId: string, options?: SvixPaginatedOptions): SvixPaginatedData<MessageEndpointOut>
```

#### `useMessageAttempt`
List all attempts for a single message by message ID ([docs](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.list-by-msg)).

```typescript
function useMessageAttempts(messageId: string, options?: SvixPaginatedOptionsAttempts): SvixPaginatedData<MessageAttemptOut>
```

#### `useAttemptFunctions`
Utility methods to act on a message attempt ([docs](https://api.svix.com/docs#tag/Message-Attempt/operation/v1.message-attempt.resend)).

```typescript
function useMessageAttemptFunctions(attempt: MessageAttemptOut): {
  resendAttempt: () => Promise<void>
}
```