*Schema, beside the type they infer.
@fanvue/builder-sdk
The core entrypoint runs on any Node, edge or browser runtime.
Client
| Symbol | Purpose | Guide |
|---|---|---|
createFanvueClient(accessToken, apiBaseUrl, options?) | Builds a FanvueClient bound to one access token. FanvueClientOptions is { apiVersion?, timeoutMs? }. | API client |
client.getCurrentUser() | GET /users/me, returns FanvueUser. | API client |
client.chats.sendMessage, client.chats.listMessages | Chat bindings. Types ChatsApi, SendMessageBody, SendMessageGif, MessageCreated, ChatMessage, ChatMessagesPage, ListMessagesQuery, TipSource. Constants CHAT_MESSAGE_MAX_CHARS, MIN_CHAT_MESSAGE_PRICE, CHAT_GIF_FORMATS, TIP_SOURCES. | API client |
client.checkout.createLink, listLinks, updateLinkStatus, deleteLink, listPayments, getPayment | Checkout link bindings. Types CheckoutApi, CheckoutLink, CheckoutLinkPriceInput, CheckoutLinkSource, CreateCheckoutLinkInput, CheckoutLinkStatusUpdate, CheckoutPayment, CheckoutPaymentsPage, CheckoutLinksPage, ListCheckoutLinksQuery, ListCheckoutPaymentsQuery, CheckoutLinkStatus, CheckoutPaymentStatus, CheckoutBillingReason, CheckoutLinkCycleUnit. | API client |
classifyCheckoutForbidden(error) | Splits a checkout 403 into not_enabled or missing_scope (CheckoutForbiddenCause). | API client |
MIN_CHECKOUT_LINK_PRICE, MAX_CHECKOUT_LINK_PRICE, MAX_CHECKOUT_PAYMENTS_LIMIT, DEFAULT_CHECKOUT_PAYMENTS_LIMIT, CHECKOUT_LINKS_NOT_ENABLED_MESSAGE, CHECKOUT_LINK_CYCLE_UNITS, CHECKOUT_LINK_STATUSES, CHECKOUT_PAYMENT_STATUSES, CHECKOUT_BILLING_REASONS | Checkout bounds and enums. | API client |
client.experiences.mintPublishRequestToken, mintUnpublishRequestToken, exchangeExperienceToken | Request tokens for Fanvue’s confirmation dialog and the fan launch-token exchange. Types ExperiencesApi, MintPublishRequestTokenParams, MintUnpublishRequestTokenParams, ExchangedExperience, ExperienceExchangeResult, ExperienceExchangeFailureCause. Constant EXPERIENCE_EXCHANGE_TIMEOUT_MS. | API client |
client.experiences.list, publish, update, unpublish | Direct experience writes. Requires the experiences write API. Types AppExperience, PublishExperienceParams, PublishExperiencePricing, UpdateExperienceParams, UnpublishExperienceParams, DeclaredExperienceAction, PublishExperienceResult, UpdateExperienceResult, UnpublishExperienceResult, ExperienceWriteOutcome, ExperiencePaidImpact, ExperiencePaidImpactAcknowledgement, ExperienceWriteRefusalReason. Constant EXPERIENCE_WRITE_REFUSAL_REASONS. | API client |
client.subscribers.list, get, getIdentity | Subscriber bindings. Types SubscribersApi, Subscriber, SubscriberSubscription, SubscriberCheck, SubscriberIdentity, SubscribersPage, ListSubscribersQuery, SubscriptionStatus, SubscriberSortField. Constants SUBSCRIPTION_STATUSES, SUBSCRIBER_SORT_FIELDS. | API client |
client.vault.createUploadSession, getUploadPartUrl, completeUpload, getMedia, listMedia, getBulkMedia, listFolders, listFolderMedia, grantMedia, getEntitledMedia | Vault bindings. Types VaultApi, VaultMediaItem, VaultVariant, VaultMediaPage, VaultFolder, VaultFolderPage, BulkMediaResult, BulkMediaError, CreateUploadSessionParams, UploadSession, UploadPartUrl, UploadPart, CompleteUploadResult, ListMediaQuery, GetMediaOptions, ListFoldersQuery, ListFolderMediaQuery, GrantMediaParams, GrantMediaResult, GetEntitledMediaOptions, VaultMediaType, VaultMediaStatus, VaultVariantType, VaultMediaUsage, FolderMediaSortField. | API client |
VAULT_MEDIA_TYPES, VAULT_MEDIA_STATUSES, VAULT_VARIANT_TYPES, VAULT_MEDIA_USAGE_FILTERS, FOLDER_MEDIA_SORT_FIELDS, BULK_MEDIA_MAX_UUIDS, MEDIA_GRANT_SOURCE_MAX_LENGTH, MEDIA_GRANT_SOURCE_REF_MAX_LENGTH, MEDIA_GRANT_SOURCE_PATTERN | Vault enums and bounds. | API client |
parseListMediaQuery(params), parseGetMediaOptions(params) | Allowlist URLSearchParams into typed vault query bags. | API client |
pollUntilReady, bestVariantUrl, resolveBulkMedia, gateBulkMedia | Media helpers. Types PollUntilReadyOptions, PollUntilReadyResult, VaultMediaState, VaultMediaEntry, ResolveBulkMediaOptions, BulkMediaResolution, MediaItemFetcher, BulkMediaFetcher. Constants DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, DEFAULT_VARIANT_PREFERENCE, DEFAULT_RESOLVE_VARIANTS, DEFAULT_BULK_CONCURRENCY. | API client |
client.webhooks.createSubscription, listSubscriptions, deleteSubscription | Webhook subscription bindings. Types WebhooksApi, WebhookSubscription, CreatedWebhookSubscription, CreateWebhookSubscriptionParams. | API client |
paginateOffset(fetchPage, options?) | Async-generator walk over an offset-paginated route. Types OffsetPage, OffsetPageRequest, OffsetPageFetcher, PaginateOffsetOptions. Constants DEFAULT_MAX_RATE_LIMIT_WAITS, MAX_RATE_LIMIT_WAIT_MS, FALLBACK_RATE_LIMIT_WAIT_MS. | API client |
creatorProfileUrl, experienceDetailShareUrl, experienceShareUrl | Links back into the Fanvue web shell. Types ShellUrlResult, ShellUrlRefusal, ExperienceShareSubstitutions. | API client |
requestJson, requestText, requestRaw, toErrorResponseArm, parseRetryAfterSeconds, DEFAULT_REQUEST_TIMEOUT_MS | The shared transport, for resource modules you build yourself. Types FanvueTransportContext, FanvueRequestOptions, FanvueHttpMethod, FetchedResponse. | API client |
createChatsApi, createCheckoutApi, createExperiencesApi, createSubscribersApi, createVaultApi, createWebhooksApi | Namespace factories over a transport context. createFanvueClient calls them for you. | API client |
OAuth and sessions
| Symbol | Purpose | Guide |
|---|---|---|
createAuthorizationUrl(config, opts?) | Authorisation URL with PKCE and state. | Off-platform sign-in |
exchangeCodeForToken(config, opts) | Exchanges a code and verifier for a TokenResponse. | Off-platform sign-in |
refreshAccessToken(config, refreshToken) | Refreshes an access token. | Storage and security |
createSessionJwt(secret, payload, expiresIn?), verifySessionJwt(secret, token) | Signs and verifies the SessionPayload JWT the Next.js entrypoints use. | Run inside Fanvue |
exchangeSessionToken(config, sessionToken) | The full authorise-on-behalf exchange for an on-platform session token. | Run inside Fanvue |
requestAuthorizationCodeOnBehalf(config, sessionToken, opts) | The authorise half of the exchange alone. | Run inside Fanvue |
getSessionTokenFromUrl(url), getThemeFromUrl(url) | Read ?token= and ?theme= from the surface URL. Type FanvueTheme. | Run inside Fanvue |
OAuthConfig, TokenResponse, SessionPayload, FanvueUser, EmbeddedAuthConfig | Configuration and payload types. | Overview |
OAuthError, ApiError, SessionVerifyError, EmbeddedAuthError, JsonParseError | Error unions. | Overview |
TokenResponseSchema, FanvueUserSchema, SessionPayloadSchema, AuthorizeOnBehalfResponseSchema | Schemas for the payloads the OAuth flow parses. | Overview |
BEARER_PREFIX, HEADER_UPDATED_SESSION | Bearer and X-Updated-Session. | Run inside Fanvue |
DEFAULT_SCOPES, DEFAULT_ISSUER_URL, DEFAULT_API_BASE_URL, DEFAULT_PLATFORM_URL, API_VERSION, assertFanvueDomain(url) | Platform defaults and the domain check. | Overview |
safeJsonParse(text) | JSON parse into a Result. | Overview |
Token store and app sessions
| Symbol | Purpose | Guide |
|---|---|---|
createTokenStoreContext, storeTokenSet, getAccessToken, getAnyAppAccessToken | Encrypted token storage with compare-and-swap refresh. Types TokenStorageAdapter, TokenStoreContext, TokenStoreContextInput, StoredTokenRecord, TokenStoreError, RefreshTokenFn. Constants TOKEN_EXPIRY_MARGIN_MS, RECENT_SUBJECT_LIMIT. | Storage and security |
tokenSetFromTokenResponse, tokenSetFromOAuthResult, mapOAuthErrorToAppCode, OAUTH_APP_ERROR_CODES | Token set conversion and app-facing OAuth error codes. Types TokenSet, OAuthAppErrorCode. | Storage and security |
createAppSessions(config) | Dual-audience creator and fan session JWTs. Types AppSessions, AppSessionsConfig, CreatorSessionClaims, FanSessionClaims. Schemas CreatorSessionClaimsSchema, FanSessionClaimsSchema. Constants DEFAULT_CREATOR_TTL_SECONDS, DEFAULT_FAN_TTL_SECONDS. | Storage and security |
bearerTokenFromAuthorizationHeader(header) | Extracts the token from an Authorization header. | Storage and security |
Encryption
| Symbol | Purpose | Guide |
|---|---|---|
createFanvueCrypto(config) | AES-256-GCM over a key registry. Types FanvueCrypto, SecretCipher, CipherOptions, FanvueCryptoConfig, CryptoError. | Storage and security |
parseKeyRegistry(config), encryptedSecretKeyId(encoded) | Validates key configuration; reads the kid off a ciphertext. Type KeyRegistry. Constants DEFAULT_KEY_ID, AES_256_KEY_BYTES, KEY_ID_PATTERN, AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES. | Storage and security |
encodeBase64Url, decodeBase64Url, decodeKeyMaterial, utf8Encode, utf8Decode | Byte helpers used by the cipher. | Storage and security |
Machine auth and observability
| Symbol | Purpose | Guide |
|---|---|---|
requireMachineAuth(request, options), boundedBatchSize(requested, defaultSize, max), MINIMUM_BEARER_SECRET_LENGTH | Protect cron and queue endpoints. Types MachineAuthResult, MachineAuthOptions, SignedRequestVerifier. | Storage and security |
createSafeLogFields, createLogEvent, logEvent, errorName, BASE_ALLOWED_LOG_KEYS | Allowlisted structured logging. Types LogEvent, LogEventOptions, LogLevel, LogSink, SafeLogFields, SafeLogValue. | Storage and security |
createSentryScrubber(extraPattern?), BASE_SENSITIVE_KEY_PATTERN | A beforeSend scrubber. Type SentryScrubber. | Storage and security |
configurationReadiness(env?) | Named readiness checks. Types ReadinessCheck, ReadinessEnv. | Storage and security |
Contracts
| Symbol | Purpose | Guide |
|---|---|---|
fanvueEnv(), parseFanvueEnv(source), isFanvueConfigured(env?), flagEnabled(name, source?), resetFanvueEnvCache(), FanvueEnvSchema | The FANVUE_* environment contract. Types FanvueEnv, EnvSource. | Overview |
parseFanvueErrorBody(body), FANVUE_APP_ERROR_CODES, NON_SESSION_401_CODES | Error body parsing and app-facing codes. Types FanvueErrorBody, NormalisedFanvueError, AppErrorEnvelope, FanvueAppErrorCode, OAuthErrorBody. Schemas FanvueErrorBodySchema, FanvueMessageErrorBodySchema, FanvueErrorFieldBodySchema, FanvueIssueListErrorBodySchema, FanvueStringListErrorBodySchema, AppErrorEnvelopeSchema, OAuthErrorBodySchema. | API client |
FANVUE_ACCESS_MODES, FanvueAccessModeSchema, accessModeFromDenialReason(reason), EXPERIENCE_ENTITLED_REASONS, EXPERIENCE_DENIAL_REASONS | Access modes and entitlement reasons. Types FanvueAccessMode, ExperienceEntitledReason, ExperienceDenialReason. | Build the fan surface |
FANVUE_DELIVERY_MODES, FanvueDeliveryModeSchema | EMBEDDED and EXTERNAL. Type FanvueDeliveryMode. | Publish an experience |
FANVUE_EXPERIENCE_TYPES, FanvueExperienceTypeSchema, DEFAULT_EXPERIENCE_TYPE, ReportedExperienceTypeSchema | Experience types. Type FanvueExperienceType. | Publish an experience |
PUBLISH_REQUEST_MESSAGE, PUBLISH_RESULT_MESSAGE, UNPUBLISH_REQUEST_MESSAGE, UNPUBLISH_RESULT_MESSAGE, EXPERIENCE_MESSAGE_TYPES, isPublishResultMessage, isUnpublishResultMessage, isFanvueOrigin | The postMessage protocol between the creator surface and Fanvue’s confirmation dialog. Schemas PublishRequestMessageSchema, UnpublishRequestMessageSchema, PublishResultMessageSchema, UnpublishResultMessageSchema, PublishedExperienceFieldsSchema, ExperienceMessageSchema. | Experience messages |
MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE, clampPageSize(requested), OffsetPaginationSchema, HybridPaginationSchema, offsetPageSchema, cursorPageSchema | Pagination bounds and schemas. Types OffsetPagination, HybridPagination. | API client |
Webhooks
| Symbol | Purpose | Guide |
|---|---|---|
verifyWebhookHmac(input), computeWebhookHmac, fanvueSignatureContract(options?), rawHexSignatureContract(headerName), webhookSignatureContractFromEnv(env?), parseFanvueSignatureHeader(value), decodeHexSignature(value) | Signature verification. Types HmacContract, HeaderBag, VerifyWebhookHmacInput, WebhookCanonicalizeInput, WebhookSignatureCandidates, FanvueSignatureContractOptions, WebhookSignatureEnv. Constants FANVUE_SIGNATURE_HEADER, DEFAULT_SIGNATURE_TOLERANCE_SECONDS. | Webhooks |
resolveWebhookTopic(raw, explicitTopic?), FANVUE_WEBHOOK_EVENTS, APP_WEBHOOK_TOPICS, FanvueWebhookEventSchema, SupportedWebhookTopicSchema | Topic resolution and the topic lists. Types FanvueWebhookEvent, SupportedWebhookTopic. | Webhooks |
sanitizeWebhookDelivery(topic, raw), SanitizedWebhookEventSchema, RAW_WEBHOOK_DELIVERY_SCHEMAS and the per-topic Raw*Schema exports | Projection to a persistable event. Types SanitizedWebhookEvent, WebhookPurchaseType, WebhookTransactionStatus, WebhookTipContext. | Webhooks |
decideWebhookPreflight(input), isWebhookVerificationBody(raw), WEBHOOK_VERIFICATION_TYPE | The receiver’s first decision and the verification probe. Types ReceiverPreflight, WebhookPreflightInput. | Webhooks |
ensureWebhookSubscription(ctx), disconnectWithWebhookCleanup(ctx) | Subscription lifecycle. Types WebhookSubscriptionStore, WebhookSubscriptionRecord, UpsertWebhookSubscriptionInput, EnsureWebhookSubscriptionContext, EnsureWebhookSubscriptionResult, DisconnectWithWebhookCleanupContext, DisconnectWithWebhookCleanupResult. | Webhooks |
webhookRetryDelayMs, webhookFailureDisposition, selectReplayableEvents | Queue policy and replay selection for stored events. Types WebhookFailureDisposition, WebhookFailureInput, StoredWebhookEvent, ReplayableWebhookEvent. | Webhooks |
webhookReadiness(env?) | Readiness check for the signature configuration. Type WebhookReadinessCheck. | Webhooks |
signWebhookFixture(input), WEBHOOK_DELIVERY_FIXTURES, subscriptionNewDelivery, subscriptionRenewedDelivery, subscriptionCancelledDelivery, subscriptionExpiredDelivery, purchaseDelivery, messageDelivery, tipDelivery, refundEnvelopeDelivery, disputeEnvelopeDelivery, webhookEnvelope | Test fixtures. Types SignWebhookFixtureInput, FixtureOverrides. Constants FIXTURE_CREATOR_UUID, FIXTURE_FAN_UUID, FIXTURE_TIMESTAMP, FIXTURE_PII_CANARY. | Webhooks |
@fanvue/builder-sdk/nextjs/off-platform
| Symbol | Purpose | Guide |
|---|---|---|
createConfig(opts?), createConfigSafe(opts?) | Resolve the OAuth client from options and OAUTH_* variables. Types FanvueAuthOptions, ResolvedConfig, CreateConfigResult. | Off-platform sign-in |
createLoginHandler(opts), createCallbackHandler(opts), createLogoutHandler(opts) | The three route handlers. Type OffPlatformOptions. | Off-platform sign-in |
getSession(secret, cookieName?), getAuthenticatedClient({ sessionSecret, sessionCookieName, config }) | Read the cookie session; build a refreshed client. | Off-platform sign-in |
createWebhookReceiverHandler(ports) and its types | Same receiver as the on-platform entrypoint. | Webhooks |
@fanvue/builder-sdk/nextjs/embedded-app
| Symbol | Purpose | Guide |
|---|---|---|
createConfig(opts?) | Off-platform config plus FANVUE_PLATFORM_URL. Types EmbeddedAppAuthOptions, EmbeddedAppConfig, FanvueAuthOptions. | Run inside Fanvue |
createSessionExchangeHandler(config, hooks?) | POST route that exchanges { token } for { jwt }. Type OnTokensCallback. | Run inside Fanvue |
getSession(secret), getAuthenticatedClient({ sessionSecret, config }) | Read the Bearer session; build a client and a refreshedJwt. | Run inside Fanvue |
getSessionTokenFromUrl(url) | Re-export from the core entrypoint. | Run inside Fanvue |
withFanvueHeaders(nextConfig, options?), fanvueHeaderRules(options?), FANVUE_FRAME_ANCESTORS, FANVUE_PERMISSIONS_POLICY, FANVUE_STRICT_TRANSPORT_SECURITY | Security headers. Types FanvueHeadersOptions, NextHeaderRule, NextHeaderEntry, NextConfigWithHeaders. | Run inside Fanvue |
createCreatorSessionHandler(deps), createFanSessionHandler(deps), experienceDenialResponse(outcome) | Bootstrap routes for apps with a token store. Types CreatorSessionHandlerDeps, FanSessionHandlerDeps, CreatorSessionHooks, FanSessionHooks, CreatorSessionExchange, CreatorSessionSigner, FanSessionSigner, CreatorDevSessionStrategy, FanDevSessionStrategy, FanPreviewStrategy, CreatorSessionResponseBody, FanSessionResponseBody, FanNotEntitledResponseBody, ExperienceBindingResult. Constants DEFAULT_CREATOR_SESSION_RATE_LIMIT, DEFAULT_FAN_SESSION_RATE_LIMIT, DEFAULT_EXCHANGE_RETRY_AFTER_SECONDS. | Run inside Fanvue |
requireCreatorSession, requireFanSession, requireCreatorAccessToken | Route guards. Types CreatorSessionGuardDeps, FanSessionGuardDeps, CreatorAccessTokenGuardDeps, SessionGuardResult, CreatorAccessTokenGuardResult, CreatorSessionVerifier, FanSessionVerifier, SessionRevocationCheck. | Storage and security |
jsonError, unauthorized, forbidden, notFound, badRequest, tooManyRequests, fanvueReconnectRequired, fanvuePermissionDenied, fanvueUnavailable, internalError | Error responses on the { error: { code, message } } envelope. Type AppErrorBody. | API client |
createInMemoryRateLimiter(config?), clientIp(request), MAX_TRACKED_RATE_LIMIT_KEYS | Process-local rate limiting. Types RateLimiter, RateLimitOptions, RateLimitResult, InMemoryRateLimiterConfig. | Run inside Fanvue |
createVaultProxyHandler(deps), isSafeOpaqueId(value), DEFAULT_VAULT_RETRY_AFTER_SECONDS | Guarded proxy routes in front of the vault. Types VaultProxyHandlerDeps, VaultProxyClient, VaultProxyRouteKind, VaultProxyRouteContext, VaultListMediaQuery, VaultGetMediaOptions, VaultCreateUploadParams, VaultUploadPart. | Upload media |
oauthCallbackPageContent(appName?), oauthCallbackPageHtml(appName?), createOAuthCallbackPageHandler(appName?) | A placeholder page for the registered redirect URI, which is never visited. Type OAuthCallbackPageContent. | Run inside Fanvue |
createWebhookReceiverHandler(ports) | The webhook receiver. Types WebhookReceiverPorts, WebhookReceiverSubscription, InsertWebhookEventInput, InsertWebhookEventResult, WebhookReceiverLogger, WebhookLogFields, WebhookDiscardReason. | Webhooks |
@fanvue/builder-sdk/react
| Symbol | Purpose | Guide |
|---|---|---|
AuthProvider, useAuth() | Session JWT state and authFetch. Type AuthContextValue. | Run inside Fanvue |
useEmbeddedAuth(opts?) | Exchanges the session token on mount and returns status, error, theme. Types EmbeddedAuthStatus, UseEmbeddedAuthOptions, UseEmbeddedAuthResult, FanvueTheme. | Run inside Fanvue |
useFanvueAnalytics() | track and isEnabled. Type UseFanvueAnalyticsResult. | Host bridge |
useDialog(options?) | openDialog and isDialogAvailable. Types DialogOutcome, DialogSuccess, UseDialogOptions, UseDialogResult. | Host bridge |
@fanvue/builder-sdk/bridge
| Symbol | Purpose | Guide |
|---|---|---|
connectFanvueBridge(options?) | Opens the capability bridge. Types FanvueBridge, FanvueBridgeAnalytics, FanvueBridgeDialog, AnalyticsTrackOptions, BridgeConnectError, ConnectFanvueBridgeOptions, BridgeRequestError. | Host bridge |
bridge.analytics.track(eventName, properties?, options?) | Fires an analytics event. | Host bridge |
bridge.dialog.open(payload) | Opens a host-rendered dialog. Constant DIALOG_OPEN_TIMEOUT_MS. | Host bridge |
BRIDGE_VERSION, BRIDGE_READY_TYPE, BRIDGE_HELLO_TYPE, BRIDGE_SUPPORTED_CAPABILITIES, ANALYTICS_CAPABILITY, ANALYTICS_TRACK_METHOD, DIALOG_CAPABILITY, DIALOG_OPEN_METHOD | Protocol constants. | Host bridge |
bridgeReadyMessageSchema, bridgeHelloMessageSchema, bridgeRequestSchema, bridgeResponseSchema, bridgeCapabilitySchema, bridgeErrorCodeSchema | Envelope schemas. Types BridgeReadyMessage, BridgeHelloMessage, BridgeRequest, BridgeResponse, BridgeCapability, BridgeErrorCode. | Host bridge |
analyticsEventNameSchema, analyticsPropertiesSchema, analyticsTrackPayloadSchema, analyticsDestinationSchema | Analytics payload schemas. Types AnalyticsTrackPayload, AnalyticsProperties, AnalyticsDestination. | Host bridge |
dialogOpenPayloadSchema, dialogFieldSchema, dialogTextFieldSchema, dialogTextareaFieldSchema, dialogSelectFieldSchema, dialogSelectOptionSchema, dialogCheckboxFieldSchema, dialogValuesSchema, dialogResultSchema | Dialog payload and result schemas. Types DialogOpenPayload, DialogField, DialogSelectOption, DialogValues, DialogResult. | Host bridge |