@fanvue/builder-sdk 0.4.0 → 0.5.0

package/dist/index-ClbZoV_Z.d.ts

@@ -1,420 +0,0 @@
-import { _ as $strip, c as ZodNumber, f as ZodString, g as $loose, i as ZodDefault, l as ZodObject, r as ZodBoolean, s as ZodNullable, t as Result, u as ZodOptional } from "./index-Dr-mZ0qP.js";
-
-//#region src/core/constants.d.ts
-/** The `Bearer ` token prefix (includes trailing space). */
-declare const BEARER_PREFIX: "Bearer ";
-/** Response header carrying a refreshed session JWT back to the client. */
-declare const HEADER_UPDATED_SESSION: "X-Updated-Session";
-//#endregion
-//#region src/core/defaults.d.ts
-/** Default OAuth scopes requested during authorization. */
-declare const DEFAULT_SCOPES: "openid offline_access offline";
-/** Default OAuth issuer URL for Fanvue authentication. */
-declare const DEFAULT_ISSUER_URL: "https://auth.fanvue.com";
-/** Default base URL for the Fanvue API. */
-declare const DEFAULT_API_BASE_URL: "https://api.fanvue.com";
-/** Default base URL for the Fanvue platform (embedded authorize-on-behalf). */
-declare const DEFAULT_PLATFORM_URL: "https://www.fanvue.com";
-/** The Fanvue API version header value sent with every request. */
-declare const API_VERSION: "2025-06-26";
-/**
- * Validates that a URL belongs to the `fanvue.com` domain.
- *
- * @param url - The URL string to validate.
- * @throws If the URL is malformed or its hostname is not `fanvue.com`
- *   (or a subdomain of it).
- */
-declare function assertFanvueDomain(url: string): void;
-//#endregion
-//#region src/core/types.d.ts
-/**
- * Configuration for the OAuth client.
- *
- * @property clientId - The OAuth client ID.
- * @property clientSecret - The OAuth client secret.
- * @property redirectUri - The URI to redirect to after authentication.
- * @property issuerUrl - The OAuth issuer URL, or `null` to use the default.
- * @property apiBaseUrl - The Fanvue API base URL, or `null` to use the default.
- * @property scopes - Additional OAuth scopes to request beyond the defaults, or `null` for defaults only.
- * @property responseMode - The OAuth response mode (e.g., `fragment`), or `null` to omit.
- * @property prompt - The OAuth prompt parameter (e.g., `consent`), or `null` to omit.
- */
-interface OAuthConfig {
-  clientId: string;
-  clientSecret: string;
-  redirectUri: string;
-  issuerUrl: string | null;
-  apiBaseUrl: string | null;
-  scopes: string | null;
-  responseMode: string | null;
-  prompt: string | null;
-}
-/**
- * The raw token response returned by the OAuth token endpoint.
- *
- * @property access_token - The access token issued by the authorization server.
- * @property refresh_token - The refresh token, or `null` if not provided.
- * @property expires_in - The lifetime in seconds of the access token.
- * @property token_type - The type of the token (e.g., `Bearer`).
- * @property scope - The scope of the access token, or `null` if not provided.
- * @property id_token - The ID token, or `null` if not provided.
- */
-interface TokenResponse {
-  access_token: string;
-  refresh_token: string | null;
-  expires_in: number;
-  token_type: string;
-  scope: string | null;
-  id_token: string | null;
-}
-/**
- * The payload stored inside the encrypted session JWT.
- *
- * @property accessToken - The OAuth access token.
- * @property refreshToken - The OAuth refresh token, or `null` if unavailable.
- * @property expiresAt - The timestamp (in milliseconds) when the access token expires.
- * @property tokenType - The type of the token (e.g., `Bearer`), or `null` if unavailable.
- * @property scope - The granted scope, or `null` if unavailable.
- * @property idToken - The ID token, or `null` if unavailable.
- * @property userUuid - The unique identifier of the authenticated user.
- * @property handle - The user's handle/username.
- * @property displayName - The user's display name.
- * @property isCreator - Whether the user is a creator.
- * @property avatarUrl - The URL of the user's avatar, or `null` if not set.
- */
-interface SessionPayload {
-  accessToken: string;
-  refreshToken: string | null;
-  expiresAt: number;
-  tokenType: string | null;
-  scope: string | null;
-  idToken: string | null;
-  userUuid: string;
-  handle: string;
-  displayName: string;
-  isCreator: boolean;
-  avatarUrl: string | null;
-}
-/**
- * A Fanvue user profile as returned by the API.
- *
- * @property uuid - The unique identifier of the user.
- * @property email - The user's email address.
- * @property handle - The user's handle/username.
- * @property displayName - The user's display name.
- * @property isCreator - Whether the user is a creator.
- * @property avatarUrl - The URL of the user's avatar, or `null` if not set.
- * @property bannerUrl - The URL of the user's banner, or `null` if not set.
- * @property createdAt - The ISO 8601 timestamp of when the user was created.
- * @property updatedAt - The ISO 8601 timestamp of when the user was last updated, or `null`.
- */
-interface FanvueUser {
-  uuid: string;
-  email: string;
-  handle: string;
-  displayName: string;
-  isCreator: boolean;
-  avatarUrl: string | null;
-  bannerUrl: string | null;
-  createdAt: string;
-  updatedAt: string | null;
-}
-/**
- * Configuration for the embedded-app (delegated authorize-on-behalf) flow.
- *
- * Extends {@link OAuthConfig} with the Fanvue platform base URL that hosts
- * the `authorize-on-behalf` endpoint.
- *
- * @property platformUrl - The Fanvue platform base URL, or `null` to use the default.
- */
-interface EmbeddedAuthConfig extends OAuthConfig {
-  platformUrl: string | null;
-}
-/** Error type for JSON parsing failures. */
-type JsonParseError = {
-  code: 'JSON_PARSE_ERROR';
-  rawText: string;
-  message: string;
-};
-/** Error type for OAuth operations (token exchange, refresh). */
-type OAuthError = {
-  code: 'TOKEN_EXCHANGE_FAILED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'TOKEN_REFRESH_FAILED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'OAUTH_JSON_PARSE_ERROR';
-  rawText: string;
-  message: string;
-} | {
-  code: 'OAUTH_VALIDATION_ERROR';
-  message: string;
-};
-/** Error type for Fanvue API requests. */
-type ApiError = {
-  code: 'API_REQUEST_FAILED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'API_JSON_PARSE_ERROR';
-  rawText: string;
-  message: string;
-} | {
-  code: 'API_VALIDATION_ERROR';
-  message: string;
-};
-/** Error type for session JWT verification. */
-type SessionVerifyError = {
-  code: 'JWT_VERIFY_FAILED';
-  message: string;
-} | {
-  code: 'SESSION_VALIDATION_ERROR';
-  message: string;
-};
-/**
- * Error type for the embedded authorize-on-behalf step.
- *
- * - `SESSION_TOKEN_REJECTED` — the platform rejected the session token
- *   (missing, malformed, or expired — they live ~60 seconds). The user must
- *   reopen the embedded surface to receive a fresh one.
- * - `CONSENT_REQUIRED` — the creator has not approved (or has revoked) the
- *   in-platform consent for this app. Consent is granted in the Fanvue UI;
- *   the app cannot create it.
- * - `AUTHORIZE_ON_BEHALF_FAILED` — any other failure (network error,
- *   unexpected status). `statusCode` is `0` for network errors.
- * - `AUTHORIZE_STATE_MISMATCH` — the returned `state` did not match the one
- *   sent; the response must not be trusted.
- */
-type EmbeddedAuthError = {
-  code: 'SESSION_TOKEN_REJECTED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'CONSENT_REQUIRED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'AUTHORIZE_ON_BEHALF_FAILED';
-  statusCode: number;
-  message: string;
-} | {
-  code: 'AUTHORIZE_STATE_MISMATCH';
-  message: string;
-} | {
-  code: 'EMBEDDED_JSON_PARSE_ERROR';
-  rawText: string;
-  message: string;
-} | {
-  code: 'EMBEDDED_VALIDATION_ERROR';
-  message: string;
-};
-//#endregion
-//#region src/core/oauth.d.ts
-/**
- * Builds an OAuth 2.0 authorization URL with PKCE parameters.
- *
- * @param config - The OAuth configuration.
- * @param opts - Optional overrides. Pass `state` to use a deterministic state value.
- * @returns The authorization URL, the PKCE code verifier, and the state parameter.
- */
-declare function createAuthorizationUrl(config: OAuthConfig, opts?: {
-  state: string | null;
-} | null): Promise<{
-  url: URL;
-  codeVerifier: string;
-  state: string;
-}>;
-/**
- * Exchanges an authorization code for tokens using the OAuth token endpoint.
- *
- * @param config - The OAuth configuration.
- * @param opts - The authorization code, PKCE code verifier, and optional redirect URI override.
- * @returns A `Result` containing `TokenResponse` on success or `OAuthError` on failure.
- */
-declare function exchangeCodeForToken(config: OAuthConfig, opts: {
-  code: string;
-  codeVerifier: string;
-  redirectUri: string | null;
-}): Promise<Result<TokenResponse, OAuthError>>;
-/**
- * Refreshes an access token using a refresh token.
- *
- * @param config - The OAuth configuration.
- * @param refreshToken - The refresh token to use.
- * @returns A `Result` containing `TokenResponse` on success or `OAuthError` on failure.
- */
-declare function refreshAccessToken(config: OAuthConfig, refreshToken: string): Promise<Result<TokenResponse, OAuthError>>;
-//#endregion
-//#region src/core/session.d.ts
-/**
- * Creates a signed JWT containing the given session payload.
- *
- * @param secret - The secret key used to sign the JWT.
- * @param payload - The session data to embed in the token.
- * @param expiresIn - How long until the token expires (e.g., `"30d"`), or `null` for the default (`"30d"`).
- * @returns The signed JWT string.
- */
-declare function createSessionJwt(secret: string, payload: SessionPayload, expiresIn?: string | null): Promise<string>;
-/**
- * Verifies a session JWT and returns the validated session payload.
- *
- * @param secret - The secret key used to verify the JWT signature.
- * @param token - The JWT string to verify.
- * @returns A {@link Result} containing the validated {@link SessionPayload}, or a {@link SessionVerifyError}.
- */
-declare function verifySessionJwt(secret: string, token: string): Promise<Result<SessionPayload, SessionVerifyError>>;
-//#endregion
-//#region src/core/embedded.d.ts
-/**
- * The creator's active colour scheme, as resolved by Fanvue.
- *
- * Fanvue resolves a creator's "system" preference to the scheme actually being
- * rendered, so this is always a definite value — never `'system'`.
- */
-type FanvueTheme = 'light' | 'dark';
-/**
- * Extracts the embedded session token from a URL.
- *
- * When Fanvue opens an embedded app, it loads the app's embed URL with a
- * short-lived session token appended as a `?token=` query parameter.
- *
- * @param url - The URL to read the token from (e.g. `window.location.href`).
- * @returns The session token, or `null` when absent or the URL is malformed.
- */
-declare function getSessionTokenFromUrl(url: string | URL): string | null;
-/**
- * Extracts the creator's active colour scheme from a URL.
- *
- * When Fanvue opens an embedded app, it appends the creator's resolved colour
- * scheme as a `?theme=` query parameter (`light` or `dark`), letting the app
- * theme-match Fanvue.
- *
- * @param url - The URL to read the theme from (e.g. `window.location.href`).
- * @returns The {@link FanvueTheme}, or `null` when absent, unrecognised, or the
- *   URL is malformed (e.g. the app was opened outside Fanvue).
- */
-declare function getThemeFromUrl(url: string | URL): FanvueTheme | null;
-/**
- * Requests an authorization code from the Fanvue platform on behalf of the
- * creator currently using the embedded app.
- *
- * This is the "authorize" half of the delegated flow: the platform verifies
- * the session token, runs the OAuth authorize as the creator, and returns the
- * resulting authorization code. The PKCE verifier and client secret never
- * leave the caller — only the challenge is sent.
- *
- * Most apps should use {@link exchangeSessionToken}, which composes this with
- * the code exchange.
- *
- * @param config - The embedded auth configuration.
- * @param sessionToken - The short-lived session token received in the iframe.
- * @param opts - The PKCE code challenge and state to bind the code to.
- * @returns A `Result` containing the authorization code on success or
- *   {@link EmbeddedAuthError} on failure.
- */
-declare function requestAuthorizationCodeOnBehalf(config: EmbeddedAuthConfig, sessionToken: string, opts: {
-  codeChallenge: string;
-  state: string;
-}): Promise<Result<{
-  code: string;
-}, EmbeddedAuthError>>;
-/**
- * Exchanges an embedded session token for OAuth access and refresh tokens.
- *
- * Runs the complete delegated authorize-on-behalf flow:
- *
- * 1. Generates a PKCE verifier/challenge pair and a random `state`.
- * 2. Asks the Fanvue platform to authorize as the creator
- *    ({@link requestAuthorizationCodeOnBehalf}).
- * 3. Exchanges the returned code at the token endpoint using the client
- *    secret and PKCE verifier.
- *
- * Must run server-side: it uses the client secret. The session token should
- * be used promptly — it expires after ~60 seconds.
- *
- * @param config - The embedded auth configuration. `redirectUri` must be a
- *   redirect URI registered on the OAuth client (it is never visited; it only
- *   binds the authorization code).
- * @param sessionToken - The short-lived session token received in the iframe.
- * @returns A `Result` containing {@link TokenResponse} on success or an
- *   {@link EmbeddedAuthError} / {@link OAuthError} on failure.
- */
-declare function exchangeSessionToken(config: EmbeddedAuthConfig, sessionToken: string): Promise<Result<TokenResponse, EmbeddedAuthError | OAuthError>>;
-//#endregion
-//#region src/core/json.d.ts
-/**
- * Safely parses a JSON string, returning a `Result` instead of throwing.
- *
- * @param text - The raw text to parse as JSON.
- * @returns `ok(parsed)` on success, or `err({ code, rawText, message })` on failure.
- */
-declare function safeJsonParse(text: string): Result<unknown, JsonParseError>;
-//#endregion
-//#region src/core/schemas.d.ts
-/** Zod schema for the raw token response from the OAuth token endpoint. */
-declare const TokenResponseSchema: ZodObject<{
-  access_token: ZodString;
-  refresh_token: ZodDefault<ZodOptional<ZodNullable<ZodString>>>;
-  expires_in: ZodNumber;
-  token_type: ZodString;
-  scope: ZodDefault<ZodOptional<ZodNullable<ZodString>>>;
-  id_token: ZodDefault<ZodOptional<ZodNullable<ZodString>>>;
-}, $strip>;
-/** Zod schema for a Fanvue user profile. */
-declare const FanvueUserSchema: ZodObject<{
-  uuid: ZodString;
-  email: ZodString;
-  handle: ZodString;
-  displayName: ZodString;
-  isCreator: ZodBoolean;
-  avatarUrl: ZodNullable<ZodString>;
-  bannerUrl: ZodNullable<ZodString>;
-  createdAt: ZodString;
-  updatedAt: ZodNullable<ZodString>;
-}, $strip>;
-/** Zod schema for the authorize-on-behalf response from the Fanvue platform. */
-declare const AuthorizeOnBehalfResponseSchema: ZodObject<{
-  code: ZodString;
-  state: ZodString;
-}, $strip>;
-/** Zod schema for the session JWT payload. */
-declare const SessionPayloadSchema: ZodObject<{
-  accessToken: ZodString;
-  refreshToken: ZodNullable<ZodString>;
-  expiresAt: ZodNumber;
-  tokenType: ZodNullable<ZodString>;
-  scope: ZodNullable<ZodString>;
-  idToken: ZodNullable<ZodString>;
-  userUuid: ZodString;
-  handle: ZodString;
-  displayName: ZodString;
-  isCreator: ZodBoolean;
-  avatarUrl: ZodNullable<ZodString>;
-}, $loose>;
-//#endregion
-//#region src/core/client.d.ts
-/**
- * A client for making authenticated requests to the Fanvue API.
- */
-interface FanvueClient {
-  /**
-   * Fetches the currently authenticated user's profile.
-   *
-   * @returns A `Result` containing the {@link FanvueUser} on success or `ApiError` on failure.
-   */
-  getCurrentUser(): Promise<Result<FanvueUser, ApiError>>;
-}
-/**
- * Creates a new {@link FanvueClient} for making authenticated requests to the Fanvue API.
- *
- * @param accessToken - The OAuth access token to authenticate requests.
- * @param apiBaseUrl - The base URL for the Fanvue API, or `null` to use the default.
- * @returns A {@link FanvueClient} instance.
- */
-declare function createFanvueClient(accessToken: string, apiBaseUrl: string | null): FanvueClient;
-//#endregion
-export { DEFAULT_ISSUER_URL as A, OAuthConfig as C, TokenResponse as D, SessionVerifyError as E, HEADER_UPDATED_SESSION as F, DEFAULT_SCOPES as M, assertFanvueDomain as N, API_VERSION as O, BEARER_PREFIX as P, JsonParseError as S, SessionPayload as T, refreshAccessToken as _, SessionPayloadSchema as a, EmbeddedAuthError as b, FanvueTheme as c, getThemeFromUrl as d, requestAuthorizationCodeOnBehalf as f, exchangeCodeForToken as g, createAuthorizationUrl as h, FanvueUserSchema as i, DEFAULT_PLATFORM_URL as j, DEFAULT_API_BASE_URL as k, exchangeSessionToken as l, verifySessionJwt as m, createFanvueClient as n, TokenResponseSchema as o, createSessionJwt as p, AuthorizeOnBehalfResponseSchema as r, safeJsonParse as s, FanvueClient as t, getSessionTokenFromUrl as u, ApiError as v, OAuthError as w, FanvueUser as x, EmbeddedAuthConfig as y };
-//# sourceMappingURL=index-ClbZoV_Z.d.ts.map

package/dist/index-ClbZoV_Z.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-ClbZoV_Z.d.ts","names":[],"sources":["../src/core/constants.ts","../src/core/defaults.ts","../src/core/types.ts","../src/core/oauth.ts","../src/core/session.ts","../src/core/embedded.ts","../src/core/json.ts","../src/core/schemas.ts","../src/core/client.ts"],"mappings":"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"}