Svix React

Installation

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

App Portal usage

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:

<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:

function MyApp() {
  <SvixProvider
    token={token}
    appId={appId}
  >
    {/* Your app's components */}
  </SvixProvider>
}

The token is returned by the App Portal access endpoint (docs). 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

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.

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

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.

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 and the active app ID.

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

useEndpoints

List the application's endpoints (docs).

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

useEndpoint

Get an endpoint (docs).

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

useEndpointMessageAttempts

List message atttempts by endpoint id (docs).

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

useAttemptedMessages

List messages for a particular endpoint (docs). Additionally includes metadata about the latest message attempt.

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

useEndpointSecret

Get the endpoint's signing secret (docs).

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

useEndpointHeaders

Get the additional headers to be sent with the webhook (docs).

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
• deleteEndpoint docs
• recoverEndpointMessages: Resend all failed messages since a given time (docs)

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)

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

useNewEndpoint

Provides form state and other useful utilities for creating a new endpoint (docs).

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)

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

useMessages

List the application's messages. Messages are the webhook events being sent (docs).

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

useMessage

Get a message by its ID or eventID (docs).

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

useMessageEndpoints

List endpoints attempted by a given message (docs).

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

useMessageAttempt

List all attempts for a single message by message ID (docs).

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

useAttemptFunctions

Utility methods to act on a message attempt (docs).

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