@fanvue/builder-sdk 0.4.0 → 0.5.0

package/dist/{core-BqdYUMrJ.js → core-BhKiA55a.js}

@@ -1,10 +1,105 @@
-import { a as number, c as string, f as require_index_cjs, o as object, r as boolean } from "./schemas-DbyHF7Xi.js";
+import { a as discriminatedUnion, c as number, f as string, h as url, i as boolean, l as object, n as _enum, o as literal, p as union, r as array, s as looseObject, t as require_index_cjs, u as preprocess } from "./index.cjs-teGsk6HB.js";
 //#region src/core/constants.ts
 /** The `Bearer ` token prefix (includes trailing space). */
 const BEARER_PREFIX = "Bearer ";
 /** Response header carrying a refreshed session JWT back to the client. */
 const HEADER_UPDATED_SESSION = "X-Updated-Session";
 //#endregion
+//#region src/core/contracts/access-mode.ts
+/**
+* Experience access modes and the entitlement reasons the platform reports
+* alongside them.
+*
+* The platform's own identifier for this enum is `AccessMode`;
+* {@link FanvueAccessMode} is the SDK alias, named so it does not collide with
+* an app's own access-mode types.
+*/
+/**
+* Access modes an experience can propose or carry on Fanvue.
+*
+* - `FREE` — visible and playable by anyone.
+* - `SUBSCRIPTION` — requires an active subscription to the creator.
+* - `PAID` — requires a one-off purchase.
+* - `HIDDEN` — reachable only through a share grant, never listed.
+*/
+const FANVUE_ACCESS_MODES = [
+	"FREE",
+	"SUBSCRIPTION",
+	"PAID",
+	"HIDDEN"
+];
+/** Zod schema for {@link FanvueAccessMode}. */
+const FanvueAccessModeSchema = _enum(FANVUE_ACCESS_MODES);
+/**
+* Every reason the platform reports when a fan **is** entitled to an
+* experience, as emitted by fanguard's `resolveExperienceAccess`.
+*
+* Documented for completeness and for exhaustive logging/analytics; apps should
+* branch on `entitlement.isEntitled` rather than on a specific reason, because
+* this list grows without an API version bump.
+*
+* - `owner` — the requester is the creator who owns the experience.
+* - `entitled_via_free`, `free` — the experience is `FREE`.
+* - `entitled_via_subscription`, `subscribed` — active creator subscription.
+* - `entitled_via_share` — reached through a share grant.
+* - `purchased` — one-off purchase of the experience.
+* - `app_subscribed` — subscription to the app itself.
+* - `purchased_before_mode_change`, `app_subscribed_before_mode_change` —
+*   entitlement grandfathered from before the creator changed the access mode.
+* - `hidden_token_exchange` — the documented exemption to the fail-closed rule:
+*   a `HIDDEN` experience exchanges its token without a prior grant.
+*/
+const EXPERIENCE_ENTITLED_REASONS = [
+	"owner",
+	"entitled_via_free",
+	"entitled_via_share",
+	"entitled_via_subscription",
+	"free",
+	"subscribed",
+	"purchased",
+	"app_subscribed",
+	"purchased_before_mode_change",
+	"app_subscribed_before_mode_change",
+	"hidden_token_exchange"
+];
+/**
+* Every reason the platform reports when a fan is **denied** an experience.
+*
+* These are the only three values fanguard emits today; the type stays open for
+* forward compatibility.
+*/
+const EXPERIENCE_DENIAL_REASONS = [
+	"not_subscribed",
+	"not_purchased",
+	"no_share_grant"
+];
+/**
+* Recovers the access mode a denied experience must be in, from the denial
+* reason.
+*
+* The token exchange fails closed: an unentitled fan gets a 403 carrying only a
+* denial `reason`, and the experience payload — with it the access mode — is
+* withheld. Mapping the reason back is the only way a locked screen can show
+* the right copy ("subscribe" vs "buy" vs "ask for the link"). An unrecognised
+* reason maps to `null`, meaning "show the generic locked copy".
+*
+* @param reason - The `reason` field from the platform's 403 body.
+* @returns The implied access mode, or `null` when the reason is unrecognised.
+* @example
+* accessModeFromDenialReason('not_subscribed'); // 'SUBSCRIPTION'
+* accessModeFromDenialReason('not_purchased'); // 'PAID'
+* accessModeFromDenialReason('no_share_grant'); // 'HIDDEN'
+* accessModeFromDenialReason('something_new'); // null
+*/
+function accessModeFromDenialReason(reason) {
+	switch (reason) {
+		case "not_subscribed": return "SUBSCRIPTION";
+		case "not_purchased": return "PAID";
+		case "no_share_grant": return "HIDDEN";
+		default: return null;
+	}
+}
+//#endregion
 //#region src/core/defaults.ts
 /** Default OAuth scopes requested during authorization. */
 const DEFAULT_SCOPES = "openid offline_access offline";
@@ -32,6 +127,587 @@ function assertFanvueDomain(url) {
 	}
 	if (hostname !== "fanvue.com" && !hostname.endsWith(".fanvue.com")) throw new Error(`Invalid apiBaseUrl: "${url}" must be a fanvue.com domain (e.g. https://api.fanvue.com).`);
 }
+//#endregion
+//#region src/core/contracts/env.ts
+/**
+* The canonical `FANVUE_*` environment contract.
+*
+* Every app that embeds on Fanvue reads the same nine variables and, before
+* this module, validated them with nine slightly different schemas — one repo
+* had two incompatible ones in the same process, each with its own cache, so
+* whichever accessor ran first froze its own view of `process.env`.
+*
+* Two deliberate properties, both inherited from the app that got them right:
+*
+* - **Lazily parsed and cached.** A build must succeed without secrets, so
+*   nothing is read at import time; a bad value surfaces as a runtime failure on
+*   first use rather than at boot.
+* - **Credentials are schema-optional.** `FANVUE_APP_UUID`, `FANVUE_CLIENT_ID`,
+*   `FANVUE_CLIENT_SECRET` and `FANVUE_OAUTH_REDIRECT_URI` default to `""`
+*   instead of being required, so a preview deploy or a local checkout boots
+*   without them. {@link isFanvueConfigured} is the separate, explicit check
+*   callers run before touching an OAuth path.
+*/
+/**
+* Treats a blank string as unset.
+*
+* `.env` templates ship lines like `FANVUE_API_BASE_URL=`, and a platform
+* dashboard saves an emptied field as `""` rather than deleting it. For a
+* variable with a real default, blank must mean "use the default" — a literal
+* empty base URL would turn every request into a relative fetch.
+*/
+function blankToUndefined(value) {
+	return typeof value === "string" && value.trim() === "" ? void 0 : value;
+}
+/**
+* Zod schema for the `FANVUE_*` environment contract.
+*
+* - `FANVUE_APP_UUID` — the app's UUID on Fanvue. Checked against the `appUuid`
+*   an exchanged experience token carries, so a token minted for another app is
+*   rejected. Defaults to `""`.
+* - `FANVUE_CLIENT_ID` / `FANVUE_CLIENT_SECRET` / `FANVUE_OAUTH_REDIRECT_URI` —
+*   OAuth client credentials. Default to `""`; see {@link isFanvueConfigured}.
+* - `FANVUE_API_BASE_URL` — bare origin of the Fanvue API (no `/v0` suffix).
+*   Blank falls back to the default.
+* - `FANVUE_AUTH_BASE_URL` — origin of the Fanvue authorization server. Blank
+*   falls back to the default.
+* - `FANVUE_WEB_ORIGIN` — origin of the Fanvue web shell. The only variable
+*   with real URL validation, because it is concatenated into hrefs a creator
+*   or fan clicks: a schemeless value ships a dead link. Blank falls back to
+*   the default. Note this does not constrain the scheme.
+* - `FANVUE_API_VERSION` — value sent as `X-Fanvue-API-Version`. Blank falls
+*   back to the default.
+* - `FANVUE_EXPERIENCE_URL_TEMPLATE` — optional operator override for
+*   per-experience share links. Empty means "derive the URL".
+*/
+const FanvueEnvSchema = object({
+	FANVUE_APP_UUID: string().default(""),
+	FANVUE_CLIENT_ID: string().default(""),
+	FANVUE_CLIENT_SECRET: string().default(""),
+	FANVUE_OAUTH_REDIRECT_URI: string().default(""),
+	FANVUE_API_BASE_URL: preprocess(blankToUndefined, string().default(DEFAULT_API_BASE_URL)),
+	FANVUE_AUTH_BASE_URL: preprocess(blankToUndefined, string().default(DEFAULT_ISSUER_URL)),
+	FANVUE_WEB_ORIGIN: preprocess(blankToUndefined, url().default(DEFAULT_PLATFORM_URL)),
+	FANVUE_API_VERSION: preprocess(blankToUndefined, string().default(API_VERSION)),
+	FANVUE_EXPERIENCE_URL_TEMPLATE: string().default("")
+});
+/**
+* Validates an environment bag against {@link FanvueEnvSchema}.
+*
+* Pure and uncached — takes the environment as a parameter so it is unit
+* testable. Prefer {@link fanvueEnv} in application code.
+*
+* @param source - The variables to validate.
+* @returns The validated environment.
+* @throws If a present value fails validation (today: a non-URL
+*   `FANVUE_WEB_ORIGIN`).
+*/
+function parseFanvueEnv(source) {
+	return FanvueEnvSchema.parse(source);
+}
+let cachedEnv = null;
+const warnedFlags = /* @__PURE__ */ new Set();
+/**
+* Returns the validated `FANVUE_*` environment, parsing `process.env` on first
+* use and caching the result.
+*
+* @returns The validated environment.
+* @throws If a present value fails validation.
+* @example
+* const baseUrl = fanvueEnv().FANVUE_API_BASE_URL;
+*/
+function fanvueEnv() {
+	if (cachedEnv === null) cachedEnv = parseFanvueEnv(process.env);
+	return cachedEnv;
+}
+/**
+* Clears every piece of memoised state in this module: the {@link fanvueEnv}
+* cache and {@link flagEnabled}'s warned-flag set.
+*
+* Intended for tests, which mutate `process.env` between cases and would
+* otherwise see whichever value the first case happened to freeze. The warn-once
+* set is cleared for the same reason — left in place, whether a case sees the
+* warning depends on which case ran first.
+*/
+function resetFanvueEnvCache() {
+	cachedEnv = null;
+	warnedFlags.clear();
+}
+/**
+* Whether the four Fanvue credential variables are all set.
+*
+* Covers exactly the values OAuth configuration requires, because config
+* creation throws on a missing one and an uncaught throw in a route surfaces as
+* a 500. Call this first and return a "not configured" response instead.
+*
+* @param env - The environment to check. Defaults to the cached
+*   {@link fanvueEnv}.
+* @returns `true` when app UUID, client id, client secret and redirect URI are
+*   all non-blank. Whitespace-only counts as unset, matching how the schema
+*   treats blank values everywhere else in this module.
+* @example
+* if (!isFanvueConfigured()) {
+*   return Response.json({ error: { code: 'fanvue_not_configured', message: '…' } }, { status: 503 });
+* }
+*/
+function isFanvueConfigured(env = fanvueEnv()) {
+	return env.FANVUE_APP_UUID.trim() !== "" && env.FANVUE_CLIENT_ID.trim() !== "" && env.FANVUE_CLIENT_SECRET.trim() !== "" && env.FANVUE_OAUTH_REDIRECT_URI.trim() !== "";
+}
+/**
+* Reads a boolean environment flag.
+*
+* A strict `=== "true"` is how one app's `MCP_ENABLED="TRUE"` switched a whole
+* subsystem off in staging: every route answered 404 and the value looked
+* correct in the dashboard. A flag that fails closed on a casing typo and says
+* nothing costs more than one that is simply off, because there is no signal to
+* find. So surrounding whitespace and case do not matter, and a value that
+* still cannot be read as a boolean is warned about **once per flag name** and
+* treated as off — off is the safe answer, but not a silent one.
+*
+* @param name - The environment variable name.
+* @param source - The variables to read from. Defaults to `process.env`.
+* @returns `true` only for `"true"` (after trimming and lowercasing).
+* @see {@link resetFanvueEnvCache} to clear the warned-flag set between tests.
+* @example
+* flagEnabled('MY_APP_DEV_MODE'); // reads process.env.MY_APP_DEV_MODE
+* flagEnabled('MY_APP_DEV_MODE', { MY_APP_DEV_MODE: ' TRUE ' }); // true
+*/
+function flagEnabled(name, source = process.env) {
+	const raw = source[name];
+	const value = (raw ?? "").trim().toLowerCase();
+	if (value === "true") return true;
+	if (value !== "false" && value !== "" && !warnedFlags.has(name)) {
+		warnedFlags.add(name);
+		console.warn(`${name} is set to ${JSON.stringify(raw)}, which is not true or false. Treating it as off.`);
+	}
+	return false;
+}
+//#endregion
+//#region src/core/contracts/errors.ts
+/**
+* Error contracts: the shapes the Fanvue API puts on the wire, the envelope an
+* app puts on its own responses, and the codes that travel between them.
+*
+* The platform has **no single error envelope**. Four shapes are in production
+* use, and a machine-readable `reason` rides alongside the human text on the
+* experience-exchange 403 — losing it collapses "this fan is not entitled" into
+* "this token belongs to another app". {@link parseFanvueErrorBody} normalises
+* all four into one struct without discarding `reason`.
+*/
+/**
+* `{ message }` — 404s, contactability rejections, invalid creator UUIDs, and
+* the experience-exchange 403 (which adds `reason`). `code` appears on
+* bulk-media per-item errors.
+*/
+const FanvueMessageErrorBodySchema = looseObject({
+	message: string(),
+	reason: string().nullish().catch(null),
+	code: string().nullish().catch(null)
+});
+/**
+* `{ error }` — 401/403/500/503 and upstream tRPC failures, where `error` is the
+* human text; and `{ error, message }` — version and age-verification failures,
+* where `error` is a machine-readable code and `message` the human text.
+*/
+const FanvueErrorFieldBodySchema = looseObject({
+	error: string(),
+	message: string().nullish().catch(null),
+	reason: string().nullish().catch(null)
+});
+/** `{ errors: [{ code, message }] }` — Zod request-validation failures. */
+const FanvueIssueListErrorBodySchema = looseObject({ errors: array(looseObject({
+	code: string().nullish().catch(null),
+	message: string()
+})).min(1) });
+/** `{ errors: ["Invalid page: too small"] }` — the pagination middleware. */
+const FanvueStringListErrorBodySchema = looseObject({ errors: array(string()).min(1) });
+/**
+* Any of the four documented Fanvue API error bodies.
+*
+* Member order matters: the `errors` array shapes are tried first because they
+* carry no `message`/`error` key of their own, then `{ error }` (which may also
+* carry a `message`), then `{ message }` alone. Exported for callers that want
+* to validate a body in one step; {@link parseFanvueErrorBody} tries the members
+* individually so that one unreadable field cannot cost the whole body.
+*/
+const FanvueErrorBodySchema = union([
+	FanvueStringListErrorBodySchema,
+	FanvueIssueListErrorBodySchema,
+	FanvueErrorFieldBodySchema,
+	FanvueMessageErrorBodySchema
+]);
+/**
+* Normalises any Fanvue API error body into {@link NormalisedFanvueError}.
+*
+* Never throws and never inspects the HTTP status: a body it cannot read yields
+* an empty `message`, which the transport replaces with its own status-derived
+* text. Multiple validation issues are joined with `; ` so a single log line
+* carries all of them.
+*
+* The `{ error }` shape is disambiguated by whether a `message` sits next to it:
+* `{ error: 'age_verification_required', message: 'Verify…' }` puts the code in
+* `code` and the text in `message`, while a bare `{ error: 'Unauthorized' }` is
+* treated as text only.
+*
+* @param body - A parsed JSON body (or anything at all).
+* @returns The normalised error fields.
+* @example
+* parseFanvueErrorBody({ message: 'Fan is not entitled', reason: 'not_subscribed' });
+* // { message: 'Fan is not entitled', reason: 'not_subscribed', code: null }
+* parseFanvueErrorBody({ errors: [{ code: 'invalid_type', message: 'Expected string' }] });
+* // { message: 'Expected string', reason: null, code: 'invalid_type' }
+* parseFanvueErrorBody('<html>502</html>');
+* // { message: '', reason: null, code: null }
+*/
+function parseFanvueErrorBody(body) {
+	const stringList = FanvueStringListErrorBodySchema.safeParse(body);
+	if (stringList.success) return {
+		message: stringList.data.errors.join("; "),
+		reason: null,
+		code: null
+	};
+	const issueList = FanvueIssueListErrorBodySchema.safeParse(body);
+	if (issueList.success) {
+		const issues = issueList.data.errors;
+		return {
+			message: issues.map((issue) => issue.message).join("; "),
+			reason: null,
+			code: issues.find((issue) => typeof issue.code === "string")?.code ?? null
+		};
+	}
+	const errorField = FanvueErrorFieldBodySchema.safeParse(body);
+	if (errorField.success) {
+		const { error, message, reason } = errorField.data;
+		return {
+			message: message ?? error,
+			reason: reason ?? null,
+			code: typeof message === "string" ? error : null
+		};
+	}
+	const messageBody = FanvueMessageErrorBodySchema.safeParse(body);
+	if (messageBody.success) return {
+		message: messageBody.data.message,
+		reason: messageBody.data.reason ?? null,
+		code: messageBody.data.code ?? null
+	};
+	return {
+		message: "",
+		reason: null,
+		code: null
+	};
+}
+/**
+* Zod schema for an app's own error envelope: `{ error: { code, message } }`.
+*
+* Every Fanvue app helper produces this shape and every client parses it, so it
+* is a contract rather than a convention. The `message` is what an end user
+* reads — upstream and internal text belongs in the log, never in this body.
+*/
+const AppErrorEnvelopeSchema = object({ error: object({
+	code: string().min(1),
+	message: string()
+}) });
+/**
+* Canonical app-facing error codes for Fanvue-grant failures.
+*
+* - `fanvue_reconnect_required` (401) — the stored Fanvue grant is missing or
+*   dead. The creator must reopen the app from Fanvue.
+* - `fanvue_permission_denied` (403) — the grant is alive but lacks the scope
+*   for this capability. Reconnecting re-consents the new scope.
+* - `fanvue_api_error` (502) — the Fanvue API failed for any other reason.
+*/
+const FANVUE_APP_ERROR_CODES = {
+	reconnectRequired: "fanvue_reconnect_required",
+	permissionDenied: "fanvue_permission_denied",
+	apiError: "fanvue_api_error"
+};
+/**
+* The two 401 codes that mean the **Fanvue grant** is gone while the **app
+* session** is still valid.
+*
+* A client that treats every 401 as session expiry signs the creator out of a
+* working session and offers "Reload" — the one action that cannot restore a
+* missing grant. Check membership of this set before running expiry handling,
+* and route these to a reconnect prompt instead.
+*
+* @example
+* if (status === 401 && !NON_SESSION_401_CODES.has(code)) {
+*   onSessionExpired();
+* }
+*/
+const NON_SESSION_401_CODES = new Set([FANVUE_APP_ERROR_CODES.reconnectRequired, FANVUE_APP_ERROR_CODES.permissionDenied]);
+/**
+* Zod schema for an OAuth 2.0 error response body, normalised to camelCase.
+*
+* Only `error` and `error_description` are kept. Hydra also returns
+* `error_hint` and `error_debug`, which can echo request details back and have
+* no place in an app's own error path.
+*/
+const OAuthErrorBodySchema = looseObject({
+	error: string().min(1),
+	error_description: string().nullish()
+}).transform((raw) => ({
+	error: raw.error,
+	errorDescription: raw.error_description ?? null
+}));
+//#endregion
+//#region src/core/contracts/experience-protocol.ts
+/**
+* The `fanvue:experience:*` postMessage protocol between an embedded app and
+* the Fanvue web shell (Eden).
+*
+* Publishing is Fanvue-mediated: the app's backend mints an opaque request
+* token from the Fanvue API (`POST /v0/experiences/request-token`, scope
+* `write:experience`), the iframe posts `{ type, token }` to the parent
+* window, Fanvue verifies the token server-side and shows its native
+* "Configure Experience" modal, then replies with a result message. An app
+* never mutates Fanvue experience state directly.
+*
+* This module is the wire contract only — schemas, type guards and origin
+* validation. The browser bridge that drives the handshake (timeouts, escalation
+* to `window.top`, listener cleanup) lives outside this module.
+*/
+/** Message type an app posts to request the publish modal. */
+const PUBLISH_REQUEST_MESSAGE = "fanvue:experience:publish-request";
+/** Message type Fanvue posts back with the outcome of a publish request. */
+const PUBLISH_RESULT_MESSAGE = "fanvue:experience:publish-result";
+/** Message type an app posts to request the unpublish confirmation. */
+const UNPUBLISH_REQUEST_MESSAGE = "fanvue:experience:unpublish-request";
+/** Message type Fanvue posts back with the outcome of an unpublish request. */
+const UNPUBLISH_RESULT_MESSAGE = "fanvue:experience:unpublish-result";
+/**
+* Every message type in the protocol, in request/result pairs.
+*
+* Useful for filtering an incoming `MessageEvent` before schema validation.
+*/
+const EXPERIENCE_MESSAGE_TYPES = [
+	PUBLISH_REQUEST_MESSAGE,
+	PUBLISH_RESULT_MESSAGE,
+	UNPUBLISH_REQUEST_MESSAGE,
+	UNPUBLISH_RESULT_MESSAGE
+];
+/**
+* Zod schema for the app → Fanvue publish request.
+*
+* `token` is the opaque request token minted by
+* `POST /v0/experiences/request-token` with `action: "publish"`.
+*/
+const PublishRequestMessageSchema = object({
+	type: literal(PUBLISH_REQUEST_MESSAGE),
+	token: string().min(1)
+});
+/**
+* Zod schema for the app → Fanvue unpublish request.
+*
+* `token` is the opaque request token minted by
+* `POST /v0/experiences/request-token` with `action: "unpublish"`.
+*/
+const UnpublishRequestMessageSchema = object({
+	type: literal(UNPUBLISH_REQUEST_MESSAGE),
+	token: string().min(1)
+});
+/**
+* Zod schema for the Fanvue → app publish result.
+*
+* `experienceId` is optional rather than nullable because it mirrors the wire
+* shape: Fanvue omits the key entirely when the creator cancels. `cancelled`
+* covers both a dismissed modal and a server-side rejection of the request
+* token — the two are not distinguishable from this side.
+*
+* Any string is accepted, including `""`. A receiver must not reject an
+* otherwise well-formed result over a useless id: from the app's side a rejected
+* message is indistinguishable from no reply at all, so a publish that did
+* happen would hang until the bridge timed out. Treat a falsy `experienceId` the
+* way an absent one is treated.
+*/
+const PublishResultMessageSchema = object({
+	type: literal(PUBLISH_RESULT_MESSAGE),
+	status: _enum(["published", "cancelled"]),
+	experienceId: string().optional()
+});
+/** Zod schema for the Fanvue → app unpublish result. */
+const UnpublishResultMessageSchema = object({
+	type: literal(UNPUBLISH_RESULT_MESSAGE),
+	status: _enum(["unpublished", "cancelled"])
+});
+/**
+* Zod schema for any message in the protocol, discriminated on `type`.
+*
+* @example
+* const parsed = ExperienceMessageSchema.safeParse(event.data);
+* if (parsed.success && parsed.data.type === PUBLISH_RESULT_MESSAGE) {
+*   // parsed.data is a PublishResultMessage
+* }
+*/
+const ExperienceMessageSchema = discriminatedUnion("type", [
+	PublishRequestMessageSchema,
+	PublishResultMessageSchema,
+	UnpublishRequestMessageSchema,
+	UnpublishResultMessageSchema
+]);
+/**
+* Narrows unknown `MessageEvent` data to a {@link PublishResultMessage}.
+*
+* @param value - The raw `event.data` from a `message` event.
+* @returns `true` when the value validates against the publish-result schema.
+* @example
+* if (isPublishResultMessage(event.data) && isFanvueOrigin(event.origin)) {
+*   settle(event.data);
+* }
+*/
+function isPublishResultMessage(value) {
+	return PublishResultMessageSchema.safeParse(value).success;
+}
+/**
+* Narrows unknown `MessageEvent` data to an {@link UnpublishResultMessage}.
+*
+* @param value - The raw `event.data` from a `message` event.
+* @returns `true` when the value validates against the unpublish-result schema.
+*/
+function isUnpublishResultMessage(value) {
+	return UnpublishResultMessageSchema.safeParse(value).success;
+}
+/**
+* Whether an origin belongs to the Fanvue web shell.
+*
+* Mirrors the `frame-ancestors 'self' https://fanvue.com https://*.fanvue.com`
+* CSP allowlist every embedded app ships. Eden posts its replies with
+* `targetOrigin: "*"`, so validating `event.origin` on receipt is the only
+* app-side control against a sibling frame forging a publish success. Requires
+* `https:` — a plaintext origin is never Fanvue.
+*
+* @param origin - The `event.origin` of an incoming message.
+* @returns `true` for `https://fanvue.com` and any `https://*.fanvue.com` host.
+* @example
+* isFanvueOrigin('https://www.fanvue.com'); // true
+* isFanvueOrigin('http://fanvue.com'); // false (not https)
+* isFanvueOrigin('https://fanvue.com.evil.test'); // false
+*/
+function isFanvueOrigin(origin) {
+	let protocol;
+	let hostname;
+	try {
+		({protocol, hostname} = new URL(origin));
+	} catch {
+		return false;
+	}
+	return protocol === "https:" && (hostname === "fanvue.com" || hostname.endsWith(".fanvue.com"));
+}
+//#endregion
+//#region src/core/contracts/pagination.ts
+/**
+* Shared pagination fragments for the Fanvue API.
+*
+* The platform ships three conventions and every resource module has to pick
+* one, so the fragments live here rather than being re-declared per resource:
+*
+* 1. **Offset** (`v0`) — `?page=&size=`, response `{ data, pagination }`.
+* 2. **Cursor** (`v1` keyset and some `v0` routes) — response
+*    `{ data, nextCursor, total }`, where `total` is `null` on large keyset
+*    lists and absent entirely on the `v0` cursor routes.
+* 3. **Hybrid** (`GET /v0/subscribers`) — offset plus an optional `nextCursor`,
+*    which is `null` when sorting by name.
+*
+* This module is schemas and clamping only. The async-iterator helper that
+* walks pages while respecting rate-limit headers is a separate concern and
+* ships with the transport.
+*/
+/**
+* Largest `size` the platform accepts on an offset-paginated route.
+*
+* The API responds `400` above this, so callers clamp client-side (see
+* {@link clampPageSize}) rather than turning an over-large request into a
+* failure the caller cannot act on.
+*/
+const MAX_PAGE_SIZE = 50;
+/** The platform's default `size` when the query parameter is omitted. */
+const DEFAULT_PAGE_SIZE = 15;
+/**
+* Clamps a requested page size into the platform's accepted range.
+*
+* Non-finite and non-integer inputs fall back to {@link DEFAULT_PAGE_SIZE}
+* rather than being rounded, because a fractional `size` is a caller bug and
+* the platform would reject it.
+*
+* @param requested - The page size a caller asked for.
+* @returns An integer in `[1, MAX_PAGE_SIZE]`.
+* @example
+* clampPageSize(200); // 50
+* clampPageSize(0); // 1
+* clampPageSize(NaN); // 15
+*/
+function clampPageSize(requested) {
+	if (!Number.isInteger(requested)) return 15;
+	if (requested < 1) return 1;
+	return Math.min(requested, 50);
+}
+/**
+* Zod schema for the `pagination` object on offset-paginated `v0` responses.
+*
+* `size` is the number of items actually returned, not the requested page size
+* (styx builds it as `data.length`), and `hasMore` is the only reliable
+* end-of-list signal — the platform does not send a total on most routes.
+*
+* `size` therefore allows `0`: paging past the end returns `{ data: [], size: 0 }`,
+* which is a well-formed response and must not fail validation. The `1..50`
+* bound belongs to the *request* parameter — see {@link clampPageSize}.
+*/
+const OffsetPaginationSchema = object({
+	page: number().int().min(1),
+	size: number().int().min(0),
+	hasMore: boolean()
+});
+/**
+* Zod schema for `GET /v0/subscribers`' hybrid pagination.
+*
+* Offset fields plus a keyset cursor that is `null` when the caller sorts by
+* name (that ordering cannot be resumed from a cursor).
+*/
+const HybridPaginationSchema = OffsetPaginationSchema.extend({ nextCursor: string().nullable() });
+/**
+* Builds the response schema for an offset-paginated list of `item`.
+*
+* @param item - Schema for a single row of `data`.
+* @returns A schema for `{ data, pagination }`.
+* @example
+* const SubscribersPageSchema = offsetPageSchema(SubscriberSchema);
+* const page = SubscribersPageSchema.parse(body);
+* page.pagination.hasMore; // boolean
+*/
+function offsetPageSchema(item) {
+	return object({
+		data: array(item),
+		pagination: OffsetPaginationSchema
+	});
+}
+/**
+* Builds the response schema for a cursor-paginated list of `item`.
+*
+* `nextCursor` is `null` on the last page. Cursors are opaque and pin the
+* sort, filters and creator they were minted for, so they cannot be replayed
+* against a different query.
+*
+* `total` is the third field of the platform's `v1` keyset envelope
+* (`{ data, nextCursor, total }`): the platform sends a number only where a
+* count is free or cheap, `null` on large keyset lists (the count is the
+* expensive query keyset avoids), and the older `v0` cursor routes omit the
+* key entirely. All three normalise to `total: null` or a number here, so a
+* caller never branches on "absent vs null".
+*
+* @param item - Schema for a single row of `data`.
+* @returns A schema for `{ data, nextCursor, total }`.
+* @example
+* const PaymentsPageSchema = cursorPageSchema(CheckoutPaymentSchema);
+* const page = PaymentsPageSchema.parse(body);
+* const done = page.nextCursor === null;
+*/
+function cursorPageSchema(item) {
+	return object({
+		data: array(item),
+		nextCursor: string().nullable(),
+		total: number().nullable().default(null)
+	});
+}
 if (typeof navigator === "undefined" || !navigator.userAgent?.startsWith?.("Mozilla/5.0 "));
 const ERR_INVALID_ARG_VALUE = "ERR_INVALID_ARG_VALUE";
 const ERR_INVALID_ARG_TYPE = "ERR_INVALID_ARG_TYPE";
@@ -199,6 +875,27 @@ const SessionPayloadSchema = object({
 const CONTENT_TYPE_FORM_URLENCODED = "application/x-www-form-urlencoded";
 const OAUTH_TOKEN_ENDPOINT = "/oauth2/token";
 /**
+* Reads the authorization server's error body off a failed token response.
+*
+* The status line alone cannot separate a retired refresh token from bad client
+* credentials — both are `400` — so the body is worth keeping. Any failure to
+* read or validate it yields `null`: a missing diagnostic must never replace the
+* error it was attached to. Only `error` and `error_description` survive; the
+* provider's hint/debug fields can echo request details back.
+*/
+async function readOAuthErrorBody(response) {
+	let text;
+	try {
+		text = await response.text();
+	} catch {
+		return null;
+	}
+	const parsed = safeJsonParse(text);
+	if (parsed.isErr()) return null;
+	const validated = OAuthErrorBodySchema.safeParse(parsed.value);
+	return validated.success ? validated.data : null;
+}
+/**
 * Builds an OAuth 2.0 authorization URL with PKCE parameters.
 *
 * @param config - The OAuth configuration.
@@ -232,7 +929,9 @@ async function createAuthorizationUrl(config, opts = null) {
 *
 * @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.
+* @returns A `Result` containing `TokenResponse` on success or `OAuthError` on
+*   failure. A `TOKEN_EXCHANGE_FAILED` error carries the authorization server's
+*   own `oauthError` body when it sent a readable one.
 */
 async function exchangeCodeForToken(config, opts) {
 	const issuerUrl = config.issuerUrl ?? "https://auth.fanvue.com";
@@ -257,13 +956,15 @@ async function exchangeCodeForToken(config, opts) {
 		return (0, import_index_cjs.err)({
 			code: "TOKEN_EXCHANGE_FAILED",
 			statusCode: 0,
-			message: `Network error during token exchange: ${error instanceof Error ? error.message : String(error)}`
+			message: `Network error during token exchange: ${error instanceof Error ? error.message : String(error)}`,
+			oauthError: null
 		});
 	}
 	if (!response.ok) return (0, import_index_cjs.err)({
 		code: "TOKEN_EXCHANGE_FAILED",
 		statusCode: response.status,
-		message: `Token exchange failed: ${response.status} ${response.statusText}`
+		message: `Token exchange failed: ${response.status} ${response.statusText}`,
+		oauthError: await readOAuthErrorBody(response)
 	});
 	const parseResult = safeJsonParse(await response.text());
 	if (parseResult.isErr()) {
@@ -286,7 +987,10 @@ async function exchangeCodeForToken(config, opts) {
 *
 * @param config - The OAuth configuration.
 * @param refreshToken - The refresh token to use.
-* @returns A `Result` containing `TokenResponse` on success or `OAuthError` on failure.
+* @returns A `Result` containing `TokenResponse` on success or `OAuthError` on
+*   failure. A `TOKEN_REFRESH_FAILED` error carries the authorization server's
+*   own `oauthError` body when it sent a readable one — `invalid_grant` there
+*   means the stored refresh token is retired and the creator must reconnect.
 */
 async function refreshAccessToken(config, refreshToken) {
 	const issuerUrl = config.issuerUrl ?? "https://auth.fanvue.com";
@@ -309,13 +1013,15 @@ async function refreshAccessToken(config, refreshToken) {
 		return (0, import_index_cjs.err)({
 			code: "TOKEN_REFRESH_FAILED",
 			statusCode: 0,
-			message: `Network error during token refresh: ${error instanceof Error ? error.message : String(error)}`
+			message: `Network error during token refresh: ${error instanceof Error ? error.message : String(error)}`,
+			oauthError: null
 		});
 	}
 	if (!response.ok) return (0, import_index_cjs.err)({
 		code: "TOKEN_REFRESH_FAILED",
 		statusCode: response.status,
-		message: `Token refresh failed: ${response.status} ${response.statusText}`
+		message: `Token refresh failed: ${response.status} ${response.statusText}`,
+		oauthError: await readOAuthErrorBody(response)
 	});
 	const parseResult = safeJsonParse(await response.text());
 	if (parseResult.isErr()) {
@@ -1648,6 +2354,609 @@ function createFanvueClient(accessToken, apiBaseUrl) {
 	return { getCurrentUser };
 }
 //#endregion
-export { HEADER_UPDATED_SESSION as C, BEARER_PREFIX as S, DEFAULT_API_BASE_URL as _, requestAuthorizationCodeOnBehalf as a, DEFAULT_SCOPES as b, createAuthorizationUrl as c, AuthorizeOnBehalfResponseSchema as d, FanvueUserSchema as f, API_VERSION as g, safeJsonParse as h, getThemeFromUrl as i, exchangeCodeForToken as l, TokenResponseSchema as m, exchangeSessionToken as n, createSessionJwt as o, SessionPayloadSchema as p, getSessionTokenFromUrl as r, verifySessionJwt as s, createFanvueClient as t, refreshAccessToken as u, DEFAULT_ISSUER_URL as v, assertFanvueDomain as x, DEFAULT_PLATFORM_URL as y };
+//#region src/core/machine-auth/machine-auth.ts
+/**
+* Shortest bearer secret the SDK will compare against.
+*
+* A cron endpoint is reachable by anyone on the internet and its secret is
+* never rotated by a user, so a guessable one is a standing invitation. Below
+* this length the secret is treated as absent — the endpoint reports
+* `not_configured` instead of quietly accepting a weak credential.
+*/
+const MINIMUM_BEARER_SECRET_LENGTH = 32;
+/**
+* The `Bearer` auth scheme and its separating whitespace.
+*
+* Case-insensitive because RFC 7235 defines auth scheme names as
+* case-insensitive — `bearer` is as valid on the wire as `Bearer`. Non-global,
+* so the shared instance carries no `lastIndex` between calls.
+*/
+const BEARER_SCHEME_PATTERN = /^bearer[ \t]+/i;
+const textEncoder = new TextEncoder();
+/**
+* Compares two strings in time independent of their content.
+*
+* Hand-rolled rather than `node:crypto`'s `timingSafeEqual` because
+* `src/core` must stay runtime-agnostic — it is also imported by browser and
+* edge bundles, which a `node:crypto` import would break. This is a byte
+* comparison, not a cryptographic primitive: every byte is XOR-accumulated with
+* no early exit, and the length check happens before any comparison (an
+* unavoidable leak of length, matching `timingSafeEqual`'s own precondition).
+*/
+function constantTimeTextEqual(left, right) {
+	const leftBytes = textEncoder.encode(left);
+	const rightBytes = textEncoder.encode(right);
+	if (leftBytes.byteLength !== rightBytes.byteLength) return false;
+	let difference = 0;
+	for (let index = 0; index < leftBytes.byteLength; index += 1) difference |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+	return difference === 0;
+}
+/**
+* Reads the bearer credential from an `Authorization` header.
+*
+* The scheme is required: a bare secret in the header is rejected, so a client
+* that forgets the scheme fails loudly rather than working by accident against
+* one deployment and not another. The scheme name itself is matched
+* case-insensitively, per RFC 7235 — rejecting `bearer` would be a lie about
+* what the header means.
+*/
+function bearerToken(request) {
+	const header = request.headers.get("authorization");
+	if (header === null) return null;
+	const scheme = BEARER_SCHEME_PATTERN.exec(header);
+	if (scheme === null) return null;
+	return header.slice(scheme[0].length);
+}
+async function verifiesSignature(request, verifier, rawBody) {
+	try {
+		return await verifier.verify(request, rawBody ?? new Uint8Array(0));
+	} catch {
+		return false;
+	}
+}
+/**
+* Authenticates a machine-invoked route (cron tick, queue drain, sweeper).
+*
+* Two strategies, tried in order, either of which is sufficient:
+*
+* 1. a shared bearer secret compared in constant time, and
+* 2. an app-supplied {@link SignedRequestVerifier}.
+*
+* Deny by default. When neither strategy is usable — no verifier and a missing
+* or too-short `bearerSecret` — the result is `not_configured`, which the
+* caller should surface as 503; `unauthorized` (401) means a strategy was
+* available and the request failed it.
+*
+* Web-standard `Request` only, so this works unchanged in a Next.js route
+* handler, a Node server and an edge function.
+*
+* @param request - The incoming machine request.
+* @param options - Available credentials and strategies.
+* @returns The discriminated {@link MachineAuthResult}.
+* @example
+* // Bearer-only cron route.
+* const auth = await requireMachineAuth(request, {
+*   bearerSecret: process.env.CRON_SECRET ?? null,
+*   signedRequestVerifier: null,
+*   rawBody: null,
+* });
+* if (auth.status === 'not_configured') return new Response(null, { status: 503 });
+* if (auth.status === 'unauthorized') return new Response(null, { status: 401 });
+* @example
+* // Queue drain that also accepts QStash-signed deliveries. `@upstash/qstash`
+* // is intentionally NOT a dependency of this package — the app owns it:
+* //
+* //   import { Receiver } from '@upstash/qstash';
+* //
+* //   const qstashVerifier: SignedRequestVerifier = {
+* //     verify: async (request, rawBody) => {
+* //       const signature = request.headers.get('upstash-signature');
+* //       const currentSigningKey = process.env.QSTASH_CURRENT_SIGNING_KEY;
+* //       const nextSigningKey = process.env.QSTASH_NEXT_SIGNING_KEY;
+* //       if (!signature || !currentSigningKey || !nextSigningKey) return false;
+* //       return new Receiver({ currentSigningKey, nextSigningKey }).verify({
+* //         signature,
+* //         body: new TextDecoder().decode(rawBody),
+* //         url: request.url,
+* //         upstashRegion: request.headers.get('upstash-region') ?? undefined,
+* //       });
+* //     },
+* //   };
+* //
+* // Pass the raw bytes, never a reparsed body:
+* const rawBody = new Uint8Array(await request.arrayBuffer());
+* const auth = await requireMachineAuth(request, {
+*   bearerSecret: process.env.CRON_SECRET ?? null,
+*   signedRequestVerifier: qstashVerifier,
+*   rawBody,
+* });
+*/
+async function requireMachineAuth(request, options) {
+	const { bearerSecret, signedRequestVerifier, rawBody } = options;
+	const usableSecret = bearerSecret !== null && bearerSecret.length >= 32 ? bearerSecret : null;
+	if (usableSecret === null && signedRequestVerifier === null) return { status: "not_configured" };
+	if (usableSecret !== null) {
+		const provided = bearerToken(request);
+		if (provided !== null && constantTimeTextEqual(provided, usableSecret)) return { status: "authorized" };
+	}
+	if (signedRequestVerifier !== null) {
+		if (await verifiesSignature(request, signedRequestVerifier, rawBody)) return { status: "authorized" };
+	}
+	return { status: "unauthorized" };
+}
+/**
+* Clamps a caller-supplied batch size to a safe positive bound.
+*
+* Machine routes take `?limit=` to let an operator drain faster, which is also
+* an unauthenticated-shaped lever on database load, so the value is bounded
+* rather than trusted. Anything unparseable, non-integer, zero or negative
+* falls back to the default; the default itself is capped by `max`, so a
+* misconfigured default cannot exceed the ceiling either.
+*
+* The result is always a positive safe integer, even when `defaultSize` or
+* `max` is itself invalid (non-integer, zero or negative): a query builder
+* handed a negative limit can interpret it as "no limit" — the exact fail-open
+* this function exists to prevent — so a misconfigured constant degrades to a
+* batch size of 1, never to an unbounded one.
+*
+* @param requested - Raw query value, e.g. `searchParams.get('limit')`.
+* @param defaultSize - Size to use when `requested` is absent or invalid.
+* @param max - Hard ceiling.
+* @returns A positive safe integer batch size.
+* @example
+* boundedBatchSize(null, 20, 100); // 20
+* boundedBatchSize('0', 20, 100); // 20
+* boundedBatchSize('1000', 20, 100); // 100
+*/
+function boundedBatchSize(requested, defaultSize, max) {
+	const ceiling = Number.isSafeInteger(max) && max >= 1 ? max : 1;
+	const fallback = Number.isSafeInteger(defaultSize) && defaultSize >= 1 ? Math.min(defaultSize, ceiling) : 1;
+	if (requested === null) return fallback;
+	const parsed = Number(requested);
+	if (!Number.isSafeInteger(parsed) || parsed < 1) return fallback;
+	return Math.min(parsed, ceiling);
+}
+//#endregion
+//#region src/core/observability/email.ts
+/**
+* An email address, as a pattern source.
+*
+* Deliberately loose rather than RFC 5322: redaction must fail closed, so
+* anything shaped like `local@domain.tld` is treated as an address. The TLD is
+* required to be alphabetic so version-shaped strings (`jose@6.0.11`) and
+* `host:port` fragments are not mistaken for addresses.
+*/
+const EMAIL_SOURCE = "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}";
+/**
+* Matches an email address anywhere in a string.
+*
+* Non-global, so `.test()` is stateless and safe to share.
+*
+* @internal
+*/
+const EMAIL_PATTERN = new RegExp(EMAIL_SOURCE, "i");
+/**
+* The global variant of {@link EMAIL_PATTERN}, for replacing every address
+* inside a string. Only ever used with `String.prototype.replace`, which
+* resets `lastIndex`, so the shared instance cannot carry state between calls.
+*
+* @internal
+*/
+const EMAIL_PATTERN_GLOBAL = new RegExp(EMAIL_SOURCE, "gi");
+/**
+* The placeholder substituted for a redacted email address.
+*
+* @internal
+*/
+const REDACTED_EMAIL = "[redacted-email]";
+//#endregion
+//#region src/core/observability/uuid.ts
+/** The one pattern source both exported regexes are built from. */
+const UUID_SOURCE = `(^|[^0-9a-f])[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?![0-9a-f])`;
+/**
+* Matches a canonically-formatted UUID anywhere in a string.
+*
+* Non-global, so `.test()` is stateless and safe to share.
+*
+* @internal
+*/
+const UUID_PATTERN = new RegExp(UUID_SOURCE, "i");
+/**
+* The global variant of {@link UUID_PATTERN}, for replacing every UUID inside a
+* string rather than testing for one.
+*
+* Group 1 is whatever preceded the UUID and must be re-emitted by the
+* replacement, hence {@link REDACTED_UUID_REPLACEMENT}. Only ever used with
+* `String.prototype.replace`, which resets `lastIndex`, so the shared instance
+* cannot carry state between calls.
+*
+* @internal
+*/
+const UUID_PATTERN_GLOBAL = new RegExp(UUID_SOURCE, "gi");
+/**
+* The placeholder substituted for a redacted UUID.
+*
+* @internal
+*/
+const REDACTED_UUID = "[redacted-uuid]";
+/**
+* The replacement string to pair with {@link UUID_PATTERN_GLOBAL}: re-emits the
+* captured preceding character, then the placeholder.
+*
+* @internal
+*/
+const REDACTED_UUID_REPLACEMENT = `$1${REDACTED_UUID}`;
+//#endregion
+//#region src/core/observability/log-fields.ts
+/**
+* The generic Fanvue log keys every app shares.
+*
+* Anything app-specific (a wheel id, a bounty id, a claim status) is added per
+* app via `createSafeLogFields(['wheelId', ...])`.
+*/
+const BASE_ALLOWED_LOG_KEYS = [
+	"cause",
+	"code",
+	"creatorId",
+	"errorName",
+	"httpStatus",
+	"reason",
+	"retryCount",
+	"status"
+];
+/**
+* Builds an allowlisting log-field filter.
+*
+* The returned function is the only sanctioned way to get caller-supplied
+* fields into a log line. It fails closed in three independent ways:
+*
+* 1. A key that is not allowlisted is dropped entirely (so a new field cannot
+*    reach the logs until someone adds it to the list on purpose).
+* 2. A value that is not `string | number | boolean | null` is dropped — an
+*    `Error`, a response body or a token bag is never serialised, even under an
+*    allowlisted key.
+* 3. An allowlisted string value containing a UUID becomes `'[redacted-uuid]'`
+*    (platform UUIDs identify real people; any version matches, including v7 —
+*    see `UUID_PATTERN`), and one containing an email address becomes
+*    `'[redacted-email]'`. The whole value is replaced, not just the match,
+*    because the surrounding text is usually the same identifier restated.
+*
+* `undefined` values are dropped rather than logged as `undefined`.
+*
+* @param extraAllowedKeys - App-specific keys to allow in addition to
+*   {@link BASE_ALLOWED_LOG_KEYS}.
+* @returns A `safeLogFields(fields)` filter.
+* @example
+* const safeLogFields = createSafeLogFields(['wheelId']);
+* safeLogFields({ wheelId: 'wheel_1', retryCount: 2, accessToken: 'secret' });
+* // => { wheelId: 'wheel_1', retryCount: 2 }
+*/
+function createSafeLogFields(extraAllowedKeys = []) {
+	const allowed = new Set([...BASE_ALLOWED_LOG_KEYS, ...extraAllowedKeys]);
+	return function safeLogFields(fields = {}) {
+		const safe = {};
+		for (const [key, value] of Object.entries(fields)) {
+			if (!allowed.has(key) || value === void 0) continue;
+			if (typeof value === "string") {
+				if (UUID_PATTERN.test(value)) safe[key] = REDACTED_UUID;
+				else if (EMAIL_PATTERN.test(value)) safe[key] = REDACTED_EMAIL;
+				else safe[key] = value;
+				continue;
+			}
+			if (value === null || typeof value === "number" || typeof value === "boolean") safe[key] = value;
+		}
+		return safe;
+	};
+}
+/**
+* Reads a loggable name out of an unknown thrown value.
+*
+* Only the class name is returned — never `error.message`, which routinely
+* carries the very data the allowlist exists to keep out of the logs (upstream
+* response bodies, signed URLs, secrets embedded in connection strings).
+*
+* @param error - Any caught value.
+* @returns The `Error` subclass name, or the `typeof` of a non-Error throw.
+* @example
+* errorName(new TypeError('secret=abc')); // 'TypeError'
+* errorName('boom'); // 'string'
+*/
+function errorName(error) {
+	return error instanceof Error ? error.name : typeof error;
+}
+/**
+* Builds a structured event logger over an allowlist.
+*
+* The emitted shape is `prefix` followed by `{ event, ...safeFields }`, matching
+* the convention the apps already log in, so existing log-based dashboards keep
+* working after the lift.
+*
+* @param options - Prefix, allowlist and sink overrides. Every field is
+*   optional; the defaults are `'[fanvue]'`, `createSafeLogFields()` and the
+*   global `console`.
+* @returns A `logEvent(level, event, fields)` function.
+* @example
+* const logEvent = createLogEvent({ prefix: '[spinwheel]' });
+* logEvent('warn', 'exchange.retry', { httpStatus: 503, retryCount: 1 });
+* // [spinwheel] { event: 'exchange.retry', httpStatus: 503, retryCount: 1 }
+*/
+function createLogEvent(options) {
+	const prefix = options?.prefix ?? "[fanvue]";
+	const safeLogFields = options?.safeLogFields ?? createSafeLogFields();
+	const sink = options?.sink ?? console;
+	return function logEvent(level, event, fields = {}) {
+		const payload = {
+			event,
+			...safeLogFields(fields)
+		};
+		if (level === "error") {
+			sink.error(prefix, payload);
+			return;
+		}
+		if (level === "warn") {
+			sink.warn(prefix, payload);
+			return;
+		}
+		sink.info(prefix, payload);
+	};
+}
+/**
+* A ready-made {@link LogEvent} over the base allowlist, prefixed `[fanvue]`.
+*
+* Use {@link createLogEvent} instead when the app has its own prefix or extra
+* allowlisted keys.
+*
+* @example
+* logEvent('error', 'session.exchange_failed', { errorName: errorName(err) });
+*/
+const logEvent = createLogEvent();
+//#endregion
+//#region src/core/observability/readiness.ts
+/**
+* The four OAuth credential variables an embedded Fanvue app needs before it
+* can complete a creator connection.
+*/
+const FANVUE_OAUTH_VARS = [
+	"FANVUE_APP_UUID",
+	"FANVUE_CLIENT_ID",
+	"FANVUE_CLIENT_SECRET",
+	"FANVUE_OAUTH_REDIRECT_URI"
+];
+/**
+* The app's own public base URL, checked for an https origin.
+*
+* `FANVUE_APP_BASE_URL` is the SDK-prefixed name; `APP_BASE_URL` is accepted
+* because the apps this was lifted from already set it.
+*/
+const APP_BASE_URL_VARS = ["FANVUE_APP_BASE_URL", "APP_BASE_URL"];
+function firstSetValue(env, names) {
+	for (const name of names) {
+		const value = env[name];
+		if (value !== void 0 && value.length > 0) return value;
+	}
+	return null;
+}
+function isHttpsUrl(value) {
+	if (value === null) return false;
+	try {
+		return new URL(value).protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Reports whether the generic Fanvue configuration an embedded app depends on
+* is present, as a list of named checks suitable for a `/api/readyz` body.
+*
+* Pure by construction — the environment is a parameter, so a deployment's
+* readiness can be asserted in tests without mutating `process.env`. Two
+* checks:
+*
+* - `app_url` — the app's public base URL is set and https. Fanvue refuses to
+*   embed a non-https origin, so an http (or unset) value means creators would
+*   see an empty frame rather than an error.
+* - `fanvue_oauth` — all four OAuth credential variables are present. The
+*   detail names the missing variables, never their values.
+*
+* Provider-specific checks are deliberately out of scope: webhook signature
+* readiness belongs to the webhooks module (which owns the contract), and
+* queue/cron credentials belong to whichever machine-auth strategy the app
+* plugs in.
+*
+* @param env - Environment to read. Defaults to `process.env`; on a runtime
+*   with no `process` global (browser, some edge workers) it defaults to an
+*   empty environment, so the probe reports not-ready instead of throwing a
+*   `ReferenceError`.
+* @returns One {@link ReadinessCheck} per generic concern, in a stable order.
+* @example
+* const checks = configurationReadiness();
+* const ready = checks.every((check) => check.ready);
+* return Response.json({ ready, checks }, { status: ready ? 200 : 503 });
+*/
+function configurationReadiness(env = typeof process === "undefined" ? {} : process.env) {
+	const appUrlReady = isHttpsUrl(firstSetValue(env, APP_BASE_URL_VARS));
+	const missingOauthVars = FANVUE_OAUTH_VARS.filter((name) => {
+		const value = env[name];
+		return value === void 0 || value.length === 0;
+	});
+	return [{
+		name: "app_url",
+		ready: appUrlReady,
+		detail: appUrlReady ? null : `set ${APP_BASE_URL_VARS[0]} to an https:// origin`
+	}, {
+		name: "fanvue_oauth",
+		ready: missingOauthVars.length === 0,
+		detail: missingOauthVars.length === 0 ? null : `missing ${missingOauthVars.join(", ")}`
+	}];
+}
+//#endregion
+//#region src/core/observability/sentry-scrubber.ts
+/**
+* Key-name fragments whose values are never allowed to reach an error tracker.
+*
+* Matched as a substring, case-insensitively, so `Authorization`,
+* `authorizationHeader`, `x-authorization`, `x-api-key` and `apiKey` all hit.
+* Substring matching over-redacts on purpose (`emailSent`, `iphoneModel`) —
+* losing a benign field fails closed, letting a credential or a fan's contact
+* detail through does not. Anything app-specific (`prizedetail`, `fanhmac`,
+* `seed`, …) is added per app via the `extraSensitiveKeyPattern` argument.
+*/
+const BASE_SENSITIVE_KEY_PATTERN = /(authorization|cookie|token|secret|password|signedurl|api[-_]?key|credential|email|phone|ip[-_]?address)/i;
+/** The placeholder substituted for a value under a sensitive key. */
+const REDACTED = "[redacted]";
+/**
+* The placeholder substituted for an object already visited anywhere in this
+* event.
+*
+* The guard is per-event rather than per-branch, so a value referenced twice
+* shows as `[circular]` the second time even when there is no cycle. That is
+* deliberate: it bounds the work to one visit per node, which a branch-scoped
+* guard would not (a shallow object graph that shares children can be walked an
+* exponential number of times), and it matches how Sentry's own `normalize`
+* memoises. Same reasoning, same trade-off.
+*/
+const CIRCULAR = "[circular]";
+/** The placeholder substituted for a property whose getter threw. */
+const UNREADABLE = "[unreadable]";
+/** The placeholder substituted for a node nested deeper than {@link MAX_DEPTH}. */
+const TOO_DEEP = "[max-depth]";
+/**
+* How far into an event the scrubber will walk.
+*
+* Recursion has to be bounded: an event can carry an arbitrarily nested object
+* (a linked list, a parsed AST, a deeply chained `cause`), and blowing the call
+* stack inside `beforeSend` turns a scrub into a thrown `RangeError` — the event
+* is lost and the throw surfaces wherever Sentry was invoked. Anything deeper is
+* replaced rather than traversed, which fails closed: an untraversed subtree
+* cannot leak. Generous next to Sentry's own default normalisation depth of 3.
+*/
+const MAX_DEPTH = 32;
+/**
+* Merges the base sensitive-key pattern with an app-supplied one.
+*
+* The result is rebuilt from `source` with only the `i` flag so a caller
+* passing a `/g` pattern cannot make matching stateful (a shared `lastIndex`
+* would make redaction depend on call order — i.e. fail open intermittently).
+*/
+function mergeSensitiveKeyPattern(extra) {
+	if (extra === null) return BASE_SENSITIVE_KEY_PATTERN;
+	return new RegExp(`(?:${BASE_SENSITIVE_KEY_PATTERN.source})|(?:${extra.source})`, "i");
+}
+/**
+* Removes the credential-bearing parts of anything that parses as a URL.
+*
+* The whole query string goes, not named parameters — signed media URLs carry
+* their credential in parameters whose names differ per provider, so an
+* allowlist there would fail open. The fragment and the userinfo go for the same
+* reason: an OAuth redirect puts `access_token` in the fragment, and a
+* connection string puts the password in `user:pass@`, so keying redaction on
+* the query alone would leak both.
+*
+* A string that parses as a URL but carries none of those parts is returned
+* unchanged, so an ordinary log line that happens to look like a non-special URI
+* (`'note: something happened'`) is not mangled.
+*/
+function stripUrlCredentials(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return value;
+	}
+	if (url.search === "" && url.hash === "" && url.username === "" && url.password === "") return value;
+	url.search = "";
+	url.hash = "";
+	url.username = "";
+	url.password = "";
+	return `${url.toString()}?${REDACTED}`;
+}
+/**
+* Scrubs a string value: strips every UUID, then removes the credential-bearing
+* parts of anything that parses as a URL, then strips every email address.
+*
+* Emails go last so an address that survives URL stripping — a `mailto:` path,
+* a verification link's path segment — is still caught. A fan's email is PII in
+* its own right, and error messages routinely embed one (`user x@y.com not
+* found`).
+*/
+function scrubString(value) {
+	return stripUrlCredentials(value.replace(UUID_PATTERN_GLOBAL, REDACTED_UUID_REPLACEMENT)).replace(EMAIL_PATTERN_GLOBAL, REDACTED_EMAIL);
+}
+/**
+* Reads one property without letting a throwing getter abort the whole scrub.
+*
+* Sentry events routinely carry app objects, and a getter that throws (a lazy
+* field, a revoked proxy, a Vue/Mobx observable read outside its scope) would
+* otherwise propagate out of `beforeSend`.
+*/
+function readProperty(source, key) {
+	try {
+		return Reflect.get(source, key);
+	} catch {
+		return UNREADABLE;
+	}
+}
+function scrubValue(value, key, sensitiveKeyPattern, seen, depth) {
+	if (sensitiveKeyPattern.test(key)) return REDACTED;
+	if (typeof value === "string") return scrubString(value);
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return CIRCULAR;
+	if (depth >= MAX_DEPTH) return TOO_DEEP;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		const items = [];
+		for (let index = 0; index < value.length; index += 1) {
+			const item = readProperty(value, index);
+			items.push(scrubValue(item, key, sensitiveKeyPattern, seen, depth + 1));
+		}
+		return items;
+	}
+	const scrubbed = {};
+	for (const childKey of Object.keys(value)) scrubbed[childKey] = scrubValue(readProperty(value, childKey), childKey, sensitiveKeyPattern, seen, depth + 1);
+	return scrubbed;
+}
+/**
+* Builds a recursive `beforeSend` scrubber for Sentry (or any error tracker
+* with the same hook shape).
+*
+* Four redaction rules, applied to every node of the event:
+*
+* - a key matching {@link BASE_SENSITIVE_KEY_PATTERN} (or the app's extra
+*   pattern) has its value replaced with `'[redacted]'`, whatever its type;
+* - every UUID inside a string becomes `'[redacted-uuid]'` — any version,
+*   including v7;
+* - a string that parses as a URL keeps its origin and path but loses its query
+*   string, fragment and userinfo;
+* - every email address inside a string becomes `'[redacted-email]'`.
+*
+* Bounded and total by construction, because a `beforeSend` that throws loses
+* the event and raises inside the caller: repeat visits yield `'[circular]'`
+* (`WeakSet`), nodes past a depth of 32 yield `'[max-depth]'`, and a property
+* whose getter throws yields `'[unreadable]'`. Each of those fails closed — an
+* untraversed value cannot leak.
+*
+* Deliberately dependency-free: the event is typed structurally, so the privacy
+* behaviour is unit-testable without a Sentry client and this package takes no
+* dependency on `@sentry/*`.
+*
+* @param extraSensitiveKeyPattern - Extra key fragments to redact, merged with
+*   the base pattern. Its flags are ignored; matching is always
+*   case-insensitive and stateless.
+* @returns A function suitable for `Sentry.init({ beforeSend })`.
+* @example
+* Sentry.init({
+*   dsn,
+*   enabled: Boolean(dsn),
+*   beforeSend: createSentryScrubber(/(prizedetail|fanhmac|seed)/i),
+* });
+*/
+function createSentryScrubber(extraSensitiveKeyPattern = null) {
+	const sensitiveKeyPattern = mergeSensitiveKeyPattern(extraSensitiveKeyPattern);
+	return function scrubSentryEvent(event) {
+		return scrubValue(event, "", sensitiveKeyPattern, /* @__PURE__ */ new WeakSet(), 0);
+	};
+}
+//#endregion
+export { FanvueStringListErrorBodySchema as $, OffsetPaginationSchema as A, UNPUBLISH_REQUEST_MESSAGE as B, FanvueUserSchema as C, DEFAULT_PAGE_SIZE as D, safeJsonParse as E, ExperienceMessageSchema as F, isPublishResultMessage as G, UnpublishRequestMessageSchema as H, PUBLISH_REQUEST_MESSAGE as I, FANVUE_APP_ERROR_CODES as J, isUnpublishResultMessage as K, PUBLISH_RESULT_MESSAGE as L, cursorPageSchema as M, offsetPageSchema as N, HybridPaginationSchema as O, EXPERIENCE_MESSAGE_TYPES as P, FanvueMessageErrorBodySchema as Q, PublishRequestMessageSchema as R, AuthorizeOnBehalfResponseSchema as S, TokenResponseSchema as T, UnpublishResultMessageSchema as U, UNPUBLISH_RESULT_MESSAGE as V, isFanvueOrigin as W, FanvueErrorFieldBodySchema as X, FanvueErrorBodySchema as Y, FanvueIssueListErrorBodySchema as Z, createSessionJwt as _, FANVUE_ACCESS_MODES as _t, createLogEvent as a, flagEnabled as at, exchangeCodeForToken as b, BEARER_PREFIX as bt, logEvent as c, resetFanvueEnvCache as ct, requireMachineAuth as d, DEFAULT_ISSUER_URL as dt, NON_SESSION_401_CODES as et, createFanvueClient as f, DEFAULT_PLATFORM_URL as ft, requestAuthorizationCodeOnBehalf as g, EXPERIENCE_ENTITLED_REASONS as gt, getThemeFromUrl as h, EXPERIENCE_DENIAL_REASONS as ht, BASE_ALLOWED_LOG_KEYS as i, fanvueEnv as it, clampPageSize as j, MAX_PAGE_SIZE as k, MINIMUM_BEARER_SECRET_LENGTH as l, API_VERSION as lt, getSessionTokenFromUrl as m, assertFanvueDomain as mt, createSentryScrubber as n, parseFanvueErrorBody as nt, createSafeLogFields as o, isFanvueConfigured as ot, exchangeSessionToken as p, DEFAULT_SCOPES as pt, AppErrorEnvelopeSchema as q, configurationReadiness as r, FanvueEnvSchema as rt, errorName as s, parseFanvueEnv as st, BASE_SENSITIVE_KEY_PATTERN as t, OAuthErrorBodySchema as tt, boundedBatchSize as u, DEFAULT_API_BASE_URL as ut, verifySessionJwt as v, FanvueAccessModeSchema as vt, SessionPayloadSchema as w, refreshAccessToken as x, HEADER_UPDATED_SESSION as xt, createAuthorizationUrl as y, accessModeFromDenialReason as yt, PublishResultMessageSchema as z };
 
-//# sourceMappingURL=core-BqdYUMrJ.js.map
+//# sourceMappingURL=core-BhKiA55a.js.map