Integrations

Components and hooks for integrating third-party services via OAuth. Use RequireIntegration to gate content behind authentication, and useIntegration to access the resulting tokens inside child components.

Import

import { RequireIntegration, useIntegration } from "~lib/integrations";

RequireIntegration

A component that requires a specific OAuth integration to be present. It renders its children when the integration is authenticated, or shows a fallback authentication prompt when it is not.

API

<RequireIntegration host="auth.my-domain.com">
  <AuthenticatedContent />
</RequireIntegration>

Props

You must provide either host or name to identify the integration:

Name	Type	Required	Description
host	string	Yes (or name)	The hostname of the OAuth integration service
name	string	Yes (or host)	The name of the integration (e.g., "github")
children	ReactNode	Yes	Content to render when the integration is authenticated

Usage with host

<RequireIntegration host="auth.my-domain.com">
  <div>Authenticated!</div>
</RequireIntegration>

Usage with name

<RequireIntegration name="github">
  <div>Connected to GitHub!</div>
</RequireIntegration>

useIntegration

A context hook that returns the current integration's details. Must be used inside a component wrapped by RequireIntegration.

API

const integration = useIntegration();

Return Value

The hook returns an Integration object with the following properties:

Property	Type	Description
name	string	The name of the integration
host	string	The hostname of the integration service
accessToken	string | undefined	OAuth access token for authentication
refreshToken	string | undefined	OAuth refresh token for renewing access
expiresIn	number | undefined	Token expiration time in seconds
storedAt	number	Timestamp when the token was stored
widgetUid	string	Unique identifier for the widget
redirectUri	string	URI to redirect to after authentication

Examples

Complete Integration Flow

Wrap your widget in RequireIntegration, then use useIntegration in a child component to access the access token for API calls:

import { RequireIntegration, useIntegration } from "~lib/integrations";
import { useFetch } from "~lib/use-fetch";

const GitHubProfile = () => {
  const integration = useIntegration();

  const { data } = useFetch<{ login: string; avatar_url: string }>(
    "https://api.github.com/user",
    {
      headers: {
        Authorization: `Bearer ${integration.accessToken}`,
      },
    },
  );

  return (
    <div>
      <img src={data.avatar_url} alt={data.login} width="64" />
      <p>{data.login}</p>
    </div>
  );
};

export const Widget = () => {
  return (
    <RequireIntegration name="github">
      <GitHubProfile />
    </RequireIntegration>
  );
};

See Also

• useFetch - For making authenticated API calls with the access token
• useStorage - Lower-level storage used by integrations internally