> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder SDK overview

> Install @fanvue/builder-sdk, pick the entrypoint for your runtime and app type, and set its environment variables, defaults and Result handling.

`@fanvue/builder-sdk` is the TypeScript package for Fanvue apps. It runs OAuth and sessions, gives you a typed API client, verifies webhooks and talks to the Fanvue host from inside an iframe. Install it here, pick the entrypoint that matches where your code runs, then follow the guide for your app type. You need a registered app and its OAuth credentials from the Developer Area.

## Install

Install the package once; every entrypoint ships in it. The Builder SDK guides use version 0.8.0.

```bash theme={null}
npm install @fanvue/builder-sdk
```

The package declares two optional peer dependencies. Install only the ones your entrypoints need.

| Peer dependency | Version | Needed by |
| - | - | - |
| `next` | `>=14.0.0` | `nextjs/off-platform`, `nextjs/embedded-app` |
| `react` | `>=18.0.0` | `react` |

An API-only app installs neither. The package declares no Node version requirement.

## Entrypoints

Each entrypoint is a separate import path. Pick the one for where the code runs and which app type you're building.

| Import path | Contents | Runtime | App type |
| - | - | - | - |
| `@fanvue/builder-sdk` | OAuth primitives, API client, webhook helpers, encryption, token store, contracts, logging | Any Node, edge or browser runtime | All. An API-only app uses only this entrypoint. |
| `@fanvue/builder-sdk/nextjs/off-platform` | Login, callback and logout route handlers, cookie session, `getAuthenticatedClient` | Next.js App Router | Off-platform |
| `@fanvue/builder-sdk/nextjs/embedded-app` | Session exchange, security headers, creator and fan session handlers, route guards, vault proxy, webhook receiver | Next.js App Router | On-platform |
| `@fanvue/builder-sdk/react` | `AuthProvider`, `useAuth`, `useEmbeddedAuth`, `useFanvueAnalytics`, `useDialog` | React 18 or later in the browser | On-platform |
| `@fanvue/builder-sdk/bridge` | `connectFanvueBridge` and the bridge protocol schemas, for surfaces without React | Browser, inside a Fanvue iframe | On-platform |

## Environment variables

The SDK reads two sets of variables, and an app can use either or both. The `OAUTH_*` set feeds `createConfig` in both Next.js entrypoints. The `FANVUE_*` set feeds `fanvueEnv()`, the session handlers and the readiness checks.

| Variable | Required | Read by |
| - | - | - |
| `OAUTH_CLIENT_ID` | Yes | `createConfig`, `createConfigSafe` |
| `OAUTH_CLIENT_SECRET` | Yes | `createConfig`, `createConfigSafe` |
| `OAUTH_REDIRECT_URI` | Yes | `createConfig`, `createConfigSafe` |
| `SESSION_SECRET` | Yes | `createConfig`, `createConfigSafe`. Use at least 32 characters. `createConfig` accepts any length, but `createAppSessions` and `requireMachineAuth` refuse shorter secrets. |
| `OAUTH_ISSUER_BASE_URL` | No | `createConfig`. Default `https://auth.fanvue.com`. |
| `API_BASE_URL` | No | `createConfig`. Default `https://api.fanvue.com`. Must be a `fanvue.com` host. |
| `OAUTH_SCOPES` | No | `createConfig`. Space-separated scopes added to the defaults. |
| `OAUTH_RESPONSE_MODE` | No | `createConfig`. Set `form_post` to receive the callback as a `POST`. |
| `OAUTH_PROMPT` | No | `createConfig`. Forwarded as the `prompt` parameter of the authorisation request. |
| `BASE_URL` | No | `createConfig`. Public origin used to build redirect targets. |
| `SESSION_COOKIE_NAME` | No | `createConfig`. Default `fanvue_session`. |
| `FANVUE_PLATFORM_URL` | No | `createConfig` from `nextjs/embedded-app`. Default `https://www.fanvue.com`. |
| `FANVUE_APP_UUID` | For on-platform apps with a token store | `fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness` |
| `FANVUE_CLIENT_ID` | For on-platform apps with a token store | `fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness` |
| `FANVUE_CLIENT_SECRET` | For on-platform apps with a token store | `fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness` |
| `FANVUE_OAUTH_REDIRECT_URI` | For on-platform apps with a token store | `fanvueEnv()`, `isFanvueConfigured`, `configurationReadiness` |
| `FANVUE_API_BASE_URL` | No | `fanvueEnv()`. Default `https://api.fanvue.com`. Blank means default. |
| `FANVUE_AUTH_BASE_URL` | No | `fanvueEnv()`. Default `https://auth.fanvue.com`. Blank means default. |
| `FANVUE_WEB_ORIGIN` | No | `fanvueEnv()`. Default `https://www.fanvue.com`. Must parse as a URL. |
| `FANVUE_API_VERSION` | No | `fanvueEnv()`. Default `2025-06-26`. Pass it to `createFanvueClient` as `apiVersion`. |
| `FANVUE_EXPERIENCE_URL_TEMPLATE` | No | `fanvueEnv()`, `experienceShareUrl`. Empty means derive the URL. |
| `FANVUE_WEBHOOK_SIGNATURE_PROFILE` | For webhook receivers | `webhookSignatureContractFromEnv`. Set `fanvue-v0`. |
| `FANVUE_APP_BASE_URL` or `APP_BASE_URL` | For readiness checks | `configurationReadiness`. Must be an `https` origin. |

`createConfig` throws when a required `OAUTH_*` variable is missing. `createConfigSafe` returns `{ ok: false, missing }` instead, so a route can answer `503` rather than crash.

## Defaults

When you set nothing, the SDK falls back to these constants, exported from the core entrypoint.

| Constant | Value |
| - | - |
| `DEFAULT_SCOPES` | `openid offline_access offline`. Always requested; `OAUTH_SCOPES` adds to this set. |
| `DEFAULT_ISSUER_URL` | `https://auth.fanvue.com` |
| `DEFAULT_API_BASE_URL` | `https://api.fanvue.com` |
| `DEFAULT_PLATFORM_URL` | `https://www.fanvue.com` |
| `API_VERSION` | `2025-06-26`. Sent as `X-Fanvue-API-Version` on every client request. |

The client pins `X-Fanvue-API-Version` to `API_VERSION` unless you pass `apiVersion` in `createFanvueClient` options.

## Result type

Every network call in the SDK returns a `Result` instead of throwing. A `Result` is either `ok`, holding a `value`, or `err`, holding an `error`, so check `isOk()` or `isErr()` before you read either field.

Errors come from four unions. Each arm carries a `code` string you can branch on.

| Union | Arms | Returned by |
| - | - | - |
| `OAuthError` | `TOKEN_EXCHANGE_FAILED`, `TOKEN_REFRESH_FAILED`, `OAUTH_JSON_PARSE_ERROR`, `OAUTH_VALIDATION_ERROR` | `exchangeCodeForToken`, `refreshAccessToken` |
| `ApiError` | `API_REQUEST_FAILED`, `API_TIMEOUT`, `API_ERROR_RESPONSE`, `API_JSON_PARSE_ERROR`, `API_VALIDATION_ERROR` | Every `createFanvueClient` method |
| `SessionVerifyError` | `JWT_VERIFY_FAILED`, `SESSION_VALIDATION_ERROR` | `verifySessionJwt` |
| `EmbeddedAuthError` | `SESSION_TOKEN_REJECTED`, `CONSENT_REQUIRED`, `AUTHORIZE_ON_BEHALF_FAILED`, `AUTHORIZE_STATE_MISMATCH`, `EMBEDDED_JSON_PARSE_ERROR`, `EMBEDDED_VALIDATION_ERROR` | `exchangeSessionToken`, `requestAuthorizationCodeOnBehalf` |

The `API_ERROR_RESPONSE` arm carries `statusCode`, the platform's machine-readable `reason` when one was sent, and `retryAfterSeconds` parsed from `Retry-After` or `X-RateLimit-Reset`. Its `message` is upstream text, so log it but never render it to a user.

```typescript theme={null}
import { createFanvueClient } from "@fanvue/builder-sdk";

const client = createFanvueClient(accessToken, null);
const result = await client.getCurrentUser();

if (result.isErr()) {
  if (result.error.code === "API_ERROR_RESPONSE" && result.error.statusCode === 429) {
    console.warn("rate limited, retry after", result.error.retryAfterSeconds);
  }
  return null;
}

return result.value.handle;
```

Configuration and guard helpers never touch the network, so they return plain discriminated unions instead, such as `createConfigSafe` (`{ ok, config | missing }`), the route guards (`{ ok, session | response }`) and `requireMachineAuth` (`status`).

## Which guide next

<CardGroup cols={2}>
  <Card title="Off-platform sign-in" href="/docs/app-store/sdk/off-platform">
    Route handlers and a cookie session for a Next.js app creators sign in to.
  </Card>

  <Card title="Run inside Fanvue" href="/docs/app-store/sdk/embedded">
    Session exchange, headers and React hooks for an on-platform creator surface.
  </Card>

  <Card title="API client" href="/docs/app-store/sdk/api-client">
    Typed namespaces for chats, checkout, experiences, subscribers, vault and webhooks.
  </Card>

  <Card title="Webhooks" href="/docs/app-store/sdk/webhooks">
    The receiver route, signature verification and subscription lifecycle.
  </Card>

  <Card title="Host bridge" href="/docs/app-store/sdk/bridge">
    Analytics events and host-rendered dialogs from inside the iframe.
  </Card>

  <Card title="Storage and security" href="/docs/app-store/sdk/storage-and-security">
    Encrypted token storage, app sessions, machine auth and log scrubbing.
  </Card>
</CardGroup>

## See also

* [Choose your app type](/docs/get-started/choose-your-app-type)
* [UI Library](/docs/ui/index)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.