@fanvue/builder-sdk 0.3.0 → 0.4.0

package/dist/index-BRDYLBlc.d.ts

@@ -0,0 +1,223 @@
+import { _ as $strip, a as ZodEnum, c as ZodNumber, d as ZodRecord, f as ZodString, h as output, l as ZodObject, m as ZodUnknown, n as ZodArray, o as ZodLiteral, p as ZodUnion, r as ZodBoolean, t as Result, u as ZodOptional } from "./index-Dr-mZ0qP.js";
+
+//#region src/bridge/protocol.d.ts
+/**
+ * The bridge protocol version spoken by this SDK.
+ *
+ * Both sides send it on every message. Changes within a version must be
+ * additive; anything breaking increments the version, and the host answers the
+ * handshake with the highest version both sides speak.
+ */
+declare const BRIDGE_VERSION = 1;
+/**
+ * Message type the embedded app posts to the host to open a handshake.
+ *
+ * An app may re-announce (it re-posts `ready` until a `hello` lands, in case
+ * the host attached its listener late).
+ */
+declare const BRIDGE_READY_TYPE = "fanvue:bridge:ready";
+/**
+ * Message type the host posts back, carrying the granted capabilities and the port.
+ *
+ * The host answers each verified `ready` with a fresh `hello` and port,
+ * closing the prior port; the app adopts the newest `hello`.
+ */
+declare const BRIDGE_HELLO_TYPE = "fanvue:bridge:hello";
+/** Capability namespace for analytics (`analytics.track`). */
+declare const ANALYTICS_CAPABILITY = "analytics";
+/** Method name for tracking an analytics event. */
+declare const ANALYTICS_TRACK_METHOD = "track";
+/** The host capabilities an app can be granted. Grants are resolved server-side. */
+declare const bridgeCapabilitySchema: ZodEnum<{
+  analytics: "analytics";
+}>;
+/** A host capability an app can be granted. */
+type BridgeCapability = output<typeof bridgeCapabilitySchema>;
+/**
+ * Error codes the host can return for a request.
+ *
+ * - `capability_denied` — the app was not granted the requested capability.
+ * - `invalid_payload` — the payload failed the host's schema for the method.
+ * - `rate_limited` — the app exceeded the host's budget for the method.
+ * - `internal` — the host handler failed unexpectedly.
+ */
+declare const bridgeErrorCodeSchema: ZodEnum<{
+  capability_denied: "capability_denied";
+  invalid_payload: "invalid_payload";
+  rate_limited: "rate_limited";
+  internal: "internal";
+}>;
+/** An error code the host can return for a request. */
+type BridgeErrorCode = output<typeof bridgeErrorCodeSchema>;
+/** Schema for the `ready` message an app posts to `window.parent`. */
+declare const bridgeReadyMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:bridge:ready">;
+  v: ZodLiteral<1>;
+}, $strip>;
+/** The `ready` message an app posts to `window.parent` to open a handshake. */
+type BridgeReadyMessage = output<typeof bridgeReadyMessageSchema>;
+/** Schema for the `hello` message the host posts back with the transferred port. */
+declare const bridgeHelloMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:bridge:hello">;
+  v: ZodLiteral<1>;
+  capabilities: ZodArray<ZodEnum<{
+    analytics: "analytics";
+  }>>;
+}, $strip>;
+/** The `hello` message the host posts back, alongside the transferred port. */
+type BridgeHelloMessage = output<typeof bridgeHelloMessageSchema>;
+/**
+ * Schema for a request sent app → host over the port.
+ *
+ * Capability and method names are bounded so a misbehaving sender cannot make
+ * either side hold or log arbitrarily large strings.
+ */
+declare const bridgeRequestSchema: ZodObject<{
+  v: ZodLiteral<1>;
+  id: ZodString;
+  kind: ZodLiteral<"request">;
+  capability: ZodString;
+  method: ZodString;
+  payload: ZodUnknown;
+}, $strip>;
+/** A request sent app → host over the port, correlated to a response by `id`. */
+type BridgeRequest = output<typeof bridgeRequestSchema>;
+/**
+ * Schema for a response sent host → app over the port.
+ *
+ * The `id` and `error.message` are bounded like the request fields, so a
+ * misbehaving host cannot push oversized strings into the app.
+ */
+declare const bridgeResponseSchema: ZodObject<{
+  v: ZodLiteral<1>;
+  id: ZodString;
+  kind: ZodLiteral<"response">;
+  ok: ZodBoolean;
+  result: ZodOptional<ZodUnknown>;
+  error: ZodOptional<ZodObject<{
+    code: ZodEnum<{
+      capability_denied: "capability_denied";
+      invalid_payload: "invalid_payload";
+      rate_limited: "rate_limited";
+      internal: "internal";
+    }>;
+    message: ZodString;
+  }, $strip>>;
+}, $strip>;
+/** A response sent host → app over the port, correlated to a request by `id`. */
+type BridgeResponse = output<typeof bridgeResponseSchema>;
+/**
+ * Event names an app may emit.
+ *
+ * The host prefixes every name with `embedded_app_` before it reaches
+ * Amplitude, so an app can never emit a core platform event. Names are
+ * snake_case to match the platform's tracking-plan convention.
+ */
+declare const analyticsEventNameSchema: ZodString;
+/**
+ * Properties attached to an analytics event: a flat record of short scalars.
+ *
+ * Nesting is rejected so the payload stays cheap to validate and to read in
+ * Amplitude, and `$`-prefixed keys are rejected because Amplitude reserves them.
+ * Numbers must be finite — `Infinity` and `NaN` do not survive serialisation.
+ */
+declare const analyticsPropertiesSchema: ZodRecord<ZodString, ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>>;
+/** Schema for the payload of `analytics.track`. */
+declare const analyticsTrackPayloadSchema: ZodObject<{
+  eventName: ZodString;
+  properties: ZodOptional<ZodRecord<ZodString, ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>>>;
+}, $strip>;
+/** The payload of `analytics.track`. */
+type AnalyticsTrackPayload = output<typeof analyticsTrackPayloadSchema>;
+/** Properties attached to an analytics event. */
+type AnalyticsProperties = output<typeof analyticsPropertiesSchema>;
+//#endregion
+//#region src/bridge/bridge.d.ts
+/**
+ * Why a bridge request failed.
+ *
+ * Beyond the codes the host can return, the SDK adds `TIMEOUT` (the host never
+ * answered) and `PORT_CLOSED` (the message could not be put on the port —
+ * in practice the payload was not structured-cloneable). Note that
+ * `postMessage` on a closed port silently drops rather than throwing, so a
+ * torn-down host surfaces as `TIMEOUT`, not `PORT_CLOSED`.
+ */
+interface BridgeRequestError {
+  code: BridgeErrorCode | 'TIMEOUT' | 'PORT_CLOSED';
+  message: string;
+}
+/** The analytics capability, as exposed on a connected bridge. */
+interface FanvueBridgeAnalytics {
+  track: (eventName: string, properties?: AnalyticsProperties) => Promise<Result<void, BridgeRequestError>>;
+}
+/**
+ * A live connection to the Fanvue host page.
+ *
+ * @property capabilities - The capabilities the host granted this app.
+ * @property has - Whether a given capability was granted. Checking is
+ *   optional: calling a capability without checking is safe and returns
+ *   `capability_denied`.
+ * @property analytics - Fires events through the host page's Amplitude client.
+ */
+interface FanvueBridge {
+  capabilities: readonly BridgeCapability[];
+  has: (capability: BridgeCapability) => boolean;
+  analytics: FanvueBridgeAnalytics;
+}
+//#endregion
+//#region src/bridge/connect.d.ts
+/**
+ * Why connecting to the host failed.
+ *
+ * - `NOT_EMBEDDED` — the app is not running in an iframe, so there is no host.
+ * - `TIMEOUT` — no `hello` arrived. The page is framed by something other than
+ *   Fanvue, or Fanvue refused the handshake (unregistered embed origin).
+ */
+interface BridgeConnectError {
+  code: 'NOT_EMBEDDED' | 'TIMEOUT';
+  message: string;
+}
+/**
+ * Options for {@link connectFanvueBridge}.
+ *
+ * @property timeoutMs - How long to wait for the host's `hello`. Defaults to 3000.
+ */
+interface ConnectFanvueBridgeOptions {
+  timeoutMs?: number;
+}
+/**
+ * Opens the capability bridge to the Fanvue page hosting this app.
+ *
+ * Posts `fanvue:bridge:ready` to `window.parent` and waits for the host's
+ * `fanvue:bridge:hello`, which names the granted capabilities and transfers the
+ * `MessagePort` all later traffic flows over. The host verifies the frame's
+ * origin before replying, so a page framed by anything other than its
+ * registered Fanvue surface simply times out.
+ *
+ * `ready` is re-posted every 500ms until a `hello` lands (or the timeout
+ * fires), because the host may attach its listener after the app's first
+ * announce. The host answers each verified `ready` with a fresh `hello` and
+ * port, closing the prior port — so the bridge keeps listening for the
+ * lifetime of the connection and adopts the newest `hello` by swapping onto
+ * its port. Requests in flight on a superseded port fail by their timeouts.
+ *
+ * Calling this again is safe and is how an app reconnects after the iframe
+ * reloads: the host closes the previous port and re-handshakes.
+ *
+ * Failure is not exceptional — apps are expected to keep working standalone
+ * (local dev, previews) where the connection never succeeds.
+ *
+ * @param options - Optional overrides (e.g. a shorter `timeoutMs`).
+ * @returns A `Result` with the connected {@link FanvueBridge}, or a
+ *   {@link BridgeConnectError} when there is no host to talk to.
+ *
+ * @example
+ * const result = await connectFanvueBridge();
+ * if (result.isOk() && result.value.has('analytics')) {
+ *   await result.value.analytics.track('course_created', { chapters: 4 });
+ * }
+ */
+declare function connectFanvueBridge(options?: ConnectFanvueBridgeOptions): Promise<Result<FanvueBridge, BridgeConnectError>>;
+//#endregion
+export { bridgeCapabilitySchema as C, bridgeRequestSchema as D, bridgeReadyMessageSchema as E, bridgeResponseSchema as O, analyticsTrackPayloadSchema as S, bridgeHelloMessageSchema as T, BridgeReadyMessage as _, FanvueBridge as a, analyticsEventNameSchema as b, ANALYTICS_TRACK_METHOD as c, BRIDGE_HELLO_TYPE as d, BRIDGE_READY_TYPE as f, BridgeHelloMessage as g, BridgeErrorCode as h, BridgeRequestError as i, AnalyticsProperties as l, BridgeCapability as m, ConnectFanvueBridgeOptions as n, FanvueBridgeAnalytics as o, BRIDGE_VERSION as p, connectFanvueBridge as r, ANALYTICS_CAPABILITY as s, BridgeConnectError as t, AnalyticsTrackPayload as u, BridgeRequest as v, bridgeErrorCodeSchema as w, analyticsPropertiesSchema as x, BridgeResponse as y };
+//# sourceMappingURL=index-BRDYLBlc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-BRDYLBlc.d.ts","names":[],"sources":["../src/bridge/protocol.ts","../src/bridge/bridge.ts","../src/bridge/connect.ts"],"mappings":";;;;;AASA;;;;;cAAa,cAAA;;;;;AAgBb;;cARa,iBAAA;;;AAWb;;;;cAHa,iBAAA;AAMb;AAAA,cAHa,oBAAA;;cAGA,sBAAA;;cAGA,sBAAA,EAAsB,OAAA;;;;KAGvB,gBAAA,GAAmB,MAAA,QAAe,sBAAA;;;;;AAA9C;;;;cAUa,qBAAA,EAAqB,OAAA;;;;;;;KAQtB,eAAA,GAAkB,MAAA,QAAe,qBAAA;;cAGhC,wBAAA,EAAwB,SAAA;;;;;KAMzB,kBAAA,GAAqB,MAAA,QAAe,wBAAA;;cAGnC,wBAAA,EAAwB,SAAA;;;;;;;;KAOzB,kBAAA,GAAqB,MAAA,QAAe,wBAAA;;AAhBhD;;;;;cAwBa,mBAAA,EAAmB,SAAA;;;;;;;;;KAUpB,aAAA,GAAgB,MAAA,QAAe,mBAAA;;;;;;;cAQ9B,oBAAA,EAAoB,SAAA;;;;;;;;;;;;;;;;;KAUrB,cAAA,GAAiB,MAAA,QAAe,oBAAA;;;;;;;;cAS/B,wBAAA,EAAwB,SAAA;;;;;;;;cA0BxB,yBAAA,EAAyB,SAAA,CAAA,SAAA,EAAA,QAAA,WAAA,SAAA,EAAA,SAAA,EAAA,UAAA;;cAazB,2BAAA,EAA2B,SAAA;;;;;KAM5B,qBAAA,GAAwB,MAAA,QAAe,2BAAA;;KAGvC,mBAAA,GAAsB,MAAA,QAAe,yBAAA;;;;AA9JjD;;;;;AAQA;;;UCUiB,kBAAA;EACf,IAAA,EAAM,eAAA;EACN,OAAA;AAAA;;UAIe,qBAAA;EACf,KAAA,GACE,SAAA,UACA,UAAA,GAAa,mBAAA,KACV,OAAA,CAAQ,MAAA,OAAa,kBAAA;AAAA;;;;;ADN5B;;;;;UCkBiB,YAAA;EACf,YAAA,WAAuB,gBAAA;EACvB,GAAA,GAAM,UAAA,EAAY,gBAAA;EAClB,SAAA,EAAW,qBAAA;AAAA;;;;AD3Cb;;;;;AAQA;UEkBiB,kBAAA;EACf,IAAA;EACA,OAAA;AAAA;AFZF;;;;;AAAA,UEoBiB,0BAAA;EACf,SAAA;AAAA;;;AFfF;;;;;AAGA;;;;;;;;;AAGA;;;;;;;;;AAUA;;;;;;;iBEkCgB,mBAAA,CACd,OAAA,GAAU,0BAAA,GACT,OAAA,CAAQ,MAAA,CAAO,YAAA,EAAc,kBAAA"}

package/dist/{index-CweVyIKX.d.ts → index-C4ewLil3.d.ts}

@@ -1,4 +1,4 @@
-import { C as OAuthConfig } from "./index-pS9wR5yg.js";
+import { C as OAuthConfig } from "./index-ClbZoV_Z.js";
 
 //#region src/nextjs/index.d.ts
 /**
@@ -45,4 +45,4 @@ type ResolvedConfig = OAuthConfig & {
 declare function createConfig(opts?: FanvueAuthOptions): ResolvedConfig;
 //#endregion
 export { ResolvedConfig as n, createConfig as r, FanvueAuthOptions as t };
-//# sourceMappingURL=index-CweVyIKX.d.ts.map
+//# sourceMappingURL=index-C4ewLil3.d.ts.map

package/dist/{index-CweVyIKX.d.ts.map → index-C4ewLil3.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"index-CweVyIKX.d.ts","names":[],"sources":["../src/nextjs/index.ts"],"mappings":";;;;;AAcA;;;;;;KAAY,iBAAA;EACV,QAAA;EACA,YAAA;EACA,WAAA;EACA,SAAA;EACA,UAAA;EACA,MAAA;EACA,aAAA;EACA,iBAAA;EACA,YAAA;EACA,MAAA;EACA,OAAA;AAAA;;;;;;;KASU,cAAA,GAAiB,WAAA;EAC3B,aAAA;EACA,iBAAA;EACA,OAAA;AAAA;;;;;;;;;;iBAYc,YAAA,CAAa,IAAA,GAAO,iBAAA,GAAoB,cAAA"}
+{"version":3,"file":"index-C4ewLil3.d.ts","names":[],"sources":["../src/nextjs/index.ts"],"mappings":";;;;;AAcA;;;;;;KAAY,iBAAA;EACV,QAAA;EACA,YAAA;EACA,WAAA;EACA,SAAA;EACA,UAAA;EACA,MAAA;EACA,aAAA;EACA,iBAAA;EACA,YAAA;EACA,MAAA;EACA,OAAA;AAAA;;;;;;;KASU,cAAA,GAAiB,WAAA;EAC3B,aAAA;EACA,iBAAA;EACA,OAAA;AAAA;;;;;;;;;;iBAYc,YAAA,CAAa,IAAA,GAAO,iBAAA,GAAoB,cAAA"}

package/dist/index-ClbZoV_Z.d.ts

@@ -0,0 +1,420 @@
+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

@@ -0,0 +1 @@
+{"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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"}