@fanvue/builder-sdk 0.4.0 → 0.5.0

package/dist/index-C3CXrRiw.d.ts

@@ -0,0 +1,1412 @@
+import { C as $strip, S as $loose, _ as ZodType, a as ZodDefault, c as ZodLiteral, d as ZodObject, f as ZodOptional, g as ZodTransform, h as ZodString, i as ZodCatch, l as ZodNullable, n as ZodArray, o as ZodDiscriminatedUnion, p as ZodPipe, r as ZodBoolean, s as ZodEnum, t as Result, u as ZodNumber, v as ZodURL, x as output, y as ZodUnion } from "./index-cf3ZMnLJ.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/contracts/access-mode.d.ts
+/**
+ * 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.
+ */
+declare const FANVUE_ACCESS_MODES: readonly ["FREE", "SUBSCRIPTION", "PAID", "HIDDEN"];
+/** An experience access mode. */
+type FanvueAccessMode = (typeof FANVUE_ACCESS_MODES)[number];
+/** Zod schema for {@link FanvueAccessMode}. */
+declare const FanvueAccessModeSchema: ZodEnum<{
+  FREE: "FREE";
+  SUBSCRIPTION: "SUBSCRIPTION";
+  PAID: "PAID";
+  HIDDEN: "HIDDEN";
+}>;
+/**
+ * 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.
+ */
+declare const EXPERIENCE_ENTITLED_REASONS: readonly ["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"];
+/**
+ * A reason the platform reports for an entitled exchange.
+ *
+ * Open-ended (`string & {}`) for forward compatibility: the platform can add a
+ * reason at any time, and an app must not break on one it has not seen.
+ */
+type ExperienceEntitledReason = (typeof EXPERIENCE_ENTITLED_REASONS)[number] | (string & {});
+/**
+ * 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.
+ */
+declare const EXPERIENCE_DENIAL_REASONS: readonly ["not_subscribed", "not_purchased", "no_share_grant"];
+/**
+ * A reason the platform reports for a denied exchange.
+ *
+ * Open-ended (`string & {}`) so a newly added reason narrows to `null` in
+ * {@link accessModeFromDenialReason} instead of failing to type-check.
+ */
+type ExperienceDenialReason = (typeof EXPERIENCE_DENIAL_REASONS)[number] | (string & {});
+/**
+ * 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
+ */
+declare function accessModeFromDenialReason(reason: ExperienceDenialReason): FanvueAccessMode | null;
+//#endregion
+//#region src/core/contracts/env.d.ts
+/**
+ * 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".
+ */
+declare const FanvueEnvSchema: ZodObject<{
+  FANVUE_APP_UUID: ZodDefault<ZodString>;
+  FANVUE_CLIENT_ID: ZodDefault<ZodString>;
+  FANVUE_CLIENT_SECRET: ZodDefault<ZodString>;
+  FANVUE_OAUTH_REDIRECT_URI: ZodDefault<ZodString>;
+  FANVUE_API_BASE_URL: ZodPipe<ZodTransform<unknown, unknown>, ZodDefault<ZodString>>;
+  FANVUE_AUTH_BASE_URL: ZodPipe<ZodTransform<unknown, unknown>, ZodDefault<ZodString>>;
+  FANVUE_WEB_ORIGIN: ZodPipe<ZodTransform<unknown, unknown>, ZodDefault<ZodURL>>;
+  FANVUE_API_VERSION: ZodPipe<ZodTransform<unknown, unknown>, ZodDefault<ZodString>>;
+  FANVUE_EXPERIENCE_URL_TEMPLATE: ZodDefault<ZodString>;
+}, $strip>;
+/** The validated `FANVUE_*` environment. */
+type FanvueEnv = output<typeof FanvueEnvSchema>;
+/** A read-only view of an environment variable bag. */
+type EnvSource = Readonly<Record<string, string | undefined>>;
+/**
+ * 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`).
+ */
+declare function parseFanvueEnv(source: EnvSource): FanvueEnv;
+/**
+ * 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;
+ */
+declare function fanvueEnv(): FanvueEnv;
+/**
+ * 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.
+ */
+declare function resetFanvueEnvCache(): void;
+/**
+ * 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 });
+ * }
+ */
+declare function isFanvueConfigured(env?: FanvueEnv): boolean;
+/**
+ * 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
+ */
+declare function flagEnabled(name: string, source?: EnvSource): boolean;
+//#endregion
+//#region src/core/contracts/errors.d.ts
+/**
+ * `{ message }` — 404s, contactability rejections, invalid creator UUIDs, and
+ * the experience-exchange 403 (which adds `reason`). `code` appears on
+ * bulk-media per-item errors.
+ */
+declare const FanvueMessageErrorBodySchema: ZodObject<{
+  message: ZodString;
+  reason: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+  code: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+}, $loose>;
+/**
+ * `{ 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.
+ */
+declare const FanvueErrorFieldBodySchema: ZodObject<{
+  error: ZodString;
+  message: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+  reason: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+}, $loose>;
+/** `{ errors: [{ code, message }] }` — Zod request-validation failures. */
+declare const FanvueIssueListErrorBodySchema: ZodObject<{
+  errors: ZodArray<ZodObject<{
+    code: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+    message: ZodString;
+  }, $loose>>;
+}, $loose>;
+/** `{ errors: ["Invalid page: too small"] }` — the pagination middleware. */
+declare const FanvueStringListErrorBodySchema: ZodObject<{
+  errors: ZodArray<ZodString>;
+}, $loose>;
+/**
+ * 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.
+ */
+declare const FanvueErrorBodySchema: ZodUnion<readonly [ZodObject<{
+  errors: ZodArray<ZodString>;
+}, $loose>, ZodObject<{
+  errors: ZodArray<ZodObject<{
+    code: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+    message: ZodString;
+  }, $loose>>;
+}, $loose>, ZodObject<{
+  error: ZodString;
+  message: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+  reason: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+}, $loose>, ZodObject<{
+  message: ZodString;
+  reason: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+  code: ZodCatch<ZodOptional<ZodNullable<ZodString>>>;
+}, $loose>]>;
+/** A parsed Fanvue API error body, before normalisation. */
+type FanvueErrorBody = output<typeof FanvueErrorBodySchema>;
+/**
+ * A Fanvue API error body reduced to the three fields a caller can act on.
+ *
+ * @property message - Human-readable text for logs and debugging. Empty string
+ *   when the body carried none; callers substitute their own generic message
+ *   (which is what an end user should see — never upstream text).
+ * @property reason - The machine-readable reason, when the platform sent one.
+ *   Load-bearing on the experience exchange: a 403 **with** a reason is an
+ *   entitlement refusal, a bare 403 is an app-binding mismatch.
+ * @property code - The machine-readable code, when the platform sent one.
+ */
+type NormalisedFanvueError = {
+  message: string;
+  reason: string | null;
+  code: string | null;
+};
+/**
+ * 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 }
+ */
+declare function parseFanvueErrorBody(body: unknown): NormalisedFanvueError;
+/**
+ * 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.
+ */
+declare const AppErrorEnvelopeSchema: ZodObject<{
+  error: ZodObject<{
+    code: ZodString;
+    message: ZodString;
+  }, $strip>;
+}, $strip>;
+/** An app's error response body. */
+type AppErrorEnvelope = output<typeof AppErrorEnvelopeSchema>;
+/**
+ * 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.
+ */
+declare const FANVUE_APP_ERROR_CODES: {
+  readonly reconnectRequired: "fanvue_reconnect_required";
+  readonly permissionDenied: "fanvue_permission_denied";
+  readonly apiError: "fanvue_api_error";
+};
+/** One of the canonical app-facing Fanvue error codes. */
+type FanvueAppErrorCode = (typeof FANVUE_APP_ERROR_CODES)[keyof typeof FANVUE_APP_ERROR_CODES];
+/**
+ * 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();
+ * }
+ */
+declare const NON_SESSION_401_CODES: ReadonlySet<string>;
+/**
+ * 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.
+ */
+declare const OAuthErrorBodySchema: ZodPipe<ZodObject<{
+  error: ZodString;
+  error_description: ZodOptional<ZodNullable<ZodString>>;
+}, $loose>, ZodTransform<{
+  error: string;
+  errorDescription: string | null;
+}, {
+  [x: string]: unknown;
+  error: string;
+  error_description?: string | null | undefined;
+}>>;
+/**
+ * An OAuth 2.0 error response body.
+ *
+ * @property error - The RFC 6749 error code (`invalid_grant`, `invalid_client`,
+ *   `invalid_scope`, …). This is the distinction that tells a dead refresh token
+ *   apart from bad client credentials.
+ * @property errorDescription - The provider's human-readable description, or
+ *   `null`. For logs and debugging only.
+ */
+type OAuthErrorBody = output<typeof OAuthErrorBodySchema>;
+//#endregion
+//#region src/core/contracts/experience-protocol.d.ts
+/** Message type an app posts to request the publish modal. */
+declare const PUBLISH_REQUEST_MESSAGE: "fanvue:experience:publish-request";
+/** Message type Fanvue posts back with the outcome of a publish request. */
+declare const PUBLISH_RESULT_MESSAGE: "fanvue:experience:publish-result";
+/** Message type an app posts to request the unpublish confirmation. */
+declare const UNPUBLISH_REQUEST_MESSAGE: "fanvue:experience:unpublish-request";
+/** Message type Fanvue posts back with the outcome of an unpublish request. */
+declare 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.
+ */
+declare const EXPERIENCE_MESSAGE_TYPES: readonly ["fanvue:experience:publish-request", "fanvue:experience:publish-result", "fanvue:experience:unpublish-request", "fanvue:experience:unpublish-result"];
+/** One of the four `fanvue:experience:*` message types. */
+type ExperienceMessageType = (typeof EXPERIENCE_MESSAGE_TYPES)[number];
+/**
+ * Zod schema for the app → Fanvue publish request.
+ *
+ * `token` is the opaque request token minted by
+ * `POST /v0/experiences/request-token` with `action: "publish"`.
+ */
+declare const PublishRequestMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:experience:publish-request">;
+  token: ZodString;
+}, $strip>;
+/** The app → Fanvue publish request message. */
+type PublishRequestMessage = output<typeof PublishRequestMessageSchema>;
+/**
+ * Zod schema for the app → Fanvue unpublish request.
+ *
+ * `token` is the opaque request token minted by
+ * `POST /v0/experiences/request-token` with `action: "unpublish"`.
+ */
+declare const UnpublishRequestMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:experience:unpublish-request">;
+  token: ZodString;
+}, $strip>;
+/** The app → Fanvue unpublish request message. */
+type UnpublishRequestMessage = output<typeof UnpublishRequestMessageSchema>;
+/**
+ * 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.
+ */
+declare const PublishResultMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:experience:publish-result">;
+  status: ZodEnum<{
+    published: "published";
+    cancelled: "cancelled";
+  }>;
+  experienceId: ZodOptional<ZodString>;
+}, $strip>;
+/** The Fanvue → app publish result message. */
+type PublishResultMessage = output<typeof PublishResultMessageSchema>;
+/** Zod schema for the Fanvue → app unpublish result. */
+declare const UnpublishResultMessageSchema: ZodObject<{
+  type: ZodLiteral<"fanvue:experience:unpublish-result">;
+  status: ZodEnum<{
+    cancelled: "cancelled";
+    unpublished: "unpublished";
+  }>;
+}, $strip>;
+/** The Fanvue → app unpublish result message. */
+type UnpublishResultMessage = output<typeof UnpublishResultMessageSchema>;
+/**
+ * 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
+ * }
+ */
+declare const ExperienceMessageSchema: ZodDiscriminatedUnion<[ZodObject<{
+  type: ZodLiteral<"fanvue:experience:publish-request">;
+  token: ZodString;
+}, $strip>, ZodObject<{
+  type: ZodLiteral<"fanvue:experience:publish-result">;
+  status: ZodEnum<{
+    published: "published";
+    cancelled: "cancelled";
+  }>;
+  experienceId: ZodOptional<ZodString>;
+}, $strip>, ZodObject<{
+  type: ZodLiteral<"fanvue:experience:unpublish-request">;
+  token: ZodString;
+}, $strip>, ZodObject<{
+  type: ZodLiteral<"fanvue:experience:unpublish-result">;
+  status: ZodEnum<{
+    cancelled: "cancelled";
+    unpublished: "unpublished";
+  }>;
+}, $strip>], "type">;
+/** Any message in the `fanvue:experience:*` protocol. */
+type ExperienceMessage = output<typeof ExperienceMessageSchema>;
+/**
+ * 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);
+ * }
+ */
+declare function isPublishResultMessage(value: unknown): value is PublishResultMessage;
+/**
+ * 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.
+ */
+declare function isUnpublishResultMessage(value: unknown): value is UnpublishResultMessage;
+/**
+ * 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
+ */
+declare function isFanvueOrigin(origin: string): boolean;
+//#endregion
+//#region src/core/contracts/pagination.d.ts
+/**
+ * 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.
+ */
+declare const MAX_PAGE_SIZE = 50;
+/** The platform's default `size` when the query parameter is omitted. */
+declare 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
+ */
+declare function clampPageSize(requested: number): number;
+/**
+ * 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}.
+ */
+declare const OffsetPaginationSchema: ZodObject<{
+  page: ZodNumber;
+  size: ZodNumber;
+  hasMore: ZodBoolean;
+}, $strip>;
+/** The `pagination` object on an offset-paginated response. */
+type OffsetPagination = output<typeof OffsetPaginationSchema>;
+/**
+ * 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).
+ */
+declare const HybridPaginationSchema: ZodObject<{
+  page: ZodNumber;
+  size: ZodNumber;
+  hasMore: ZodBoolean;
+  nextCursor: ZodNullable<ZodString>;
+}, $strip>;
+/** The `pagination` object on the hybrid `v0` subscribers response. */
+type HybridPagination = output<typeof HybridPaginationSchema>;
+/**
+ * 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
+ */
+declare function offsetPageSchema<TItem extends ZodType>(item: TItem): ZodObject<{
+  data: ZodArray<TItem>;
+  pagination: typeof 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;
+ */
+declare function cursorPageSchema<TItem extends ZodType>(item: TItem): ZodObject<{
+  data: ZodArray<TItem>;
+  nextCursor: ZodNullable<ZodString>;
+  total: ZodDefault<ZodNullable<ZodNumber>>;
+}>;
+//#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).
+ *
+ * `oauthError` carries the authorization server's own error body when it sent a
+ * readable one, and is `null` for network errors and unreadable bodies. It is
+ * the only way to tell a retired refresh token (`invalid_grant` — the creator
+ * must reconnect) from bad client credentials (`invalid_client` — the app is
+ * misconfigured); `statusCode` is `400` for both. Diagnostic only: never render
+ * it to an end user.
+ */
+type OAuthError = {
+  code: 'TOKEN_EXCHANGE_FAILED';
+  statusCode: number;
+  message: string;
+  oauthError: OAuthErrorBody | null;
+} | {
+  code: 'TOKEN_REFRESH_FAILED';
+  statusCode: number;
+  message: string;
+  oauthError: OAuthErrorBody | null;
+} | {
+  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. A `TOKEN_EXCHANGE_FAILED` error carries the authorization server's
+ *   own `oauthError` body when it sent a readable one.
+ */
+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. 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.
+ */
+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
+//#region src/core/machine-auth/machine-auth.d.ts
+/**
+ * The outcome of authenticating a machine (cron / queue) request.
+ *
+ * `not_configured` is a separate arm on purpose: a deployment with no usable
+ * credential has an operator problem, not an attacker, and the two must map to
+ * different HTTP statuses (503 vs 401). Collapsing them hides a broken deploy
+ * behind what looks like ordinary auth noise, and tells a caller to retry with
+ * better credentials when no credential could ever work.
+ */
+type MachineAuthResult = {
+  status: 'authorized';
+} | {
+  status: 'unauthorized';
+} | {
+  status: 'not_configured';
+};
+/**
+ * A pluggable signed-request strategy — the second way a machine request can
+ * authenticate itself.
+ *
+ * Implemented by the app so the SDK takes no queue-provider dependency. The
+ * verifier owns its own key material and rotation; it must return `false`
+ * (never throw) when it cannot verify, though a throw is caught and treated as
+ * a failure regardless.
+ */
+interface SignedRequestVerifier {
+  /**
+   * @param request - The incoming request, whose URL and headers are usually
+   *   part of the signed material.
+   * @param rawBody - The exact bytes received. Never a reserialized body: a
+   *   round-trip through `JSON.parse`/`stringify` changes whitespace and key
+   *   order and invalidates the signature.
+   * @returns Whether the signature is authentic.
+   */
+  verify: (request: Request, rawBody: Uint8Array) => Promise<boolean>;
+}
+/**
+ * Credentials and strategies available to {@link requireMachineAuth}.
+ */
+interface MachineAuthOptions {
+  /**
+   * Shared bearer secret (the `CRON_SECRET` pattern). `null` when unset. A
+   * secret shorter than {@link MINIMUM_BEARER_SECRET_LENGTH} is treated as
+   * unset rather than compared.
+   */
+  bearerSecret: string | null;
+  /** Signed-request strategy, or `null` when the app plugs none in. */
+  signedRequestVerifier: SignedRequestVerifier | null;
+  /**
+   * The exact request bytes, required by {@link signedRequestVerifier}. `null`
+   * is allowed (and reads as an empty body) when no verifier is configured.
+   */
+  rawBody: Uint8Array | null;
+}
+/**
+ * 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.
+ */
+declare const MINIMUM_BEARER_SECRET_LENGTH = 32;
+/**
+ * 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,
+ * });
+ */
+declare function requireMachineAuth(request: Request, options: MachineAuthOptions): Promise<MachineAuthResult>;
+/**
+ * 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
+ */
+declare function boundedBatchSize(requested: string | null, defaultSize: number, max: number): number;
+//#endregion
+//#region src/core/observability/log-fields.d.ts
+/**
+ * The log levels a structured event can be emitted at.
+ */
+type LogLevel = 'info' | 'warn' | 'error';
+/**
+ * A scalar that is safe to place in a log line.
+ *
+ * Objects and arrays are deliberately absent: an allowlisted key whose value is
+ * a structure would smuggle un-reviewed fields (an Error, a token bag, a whole
+ * request) past the allowlist, so those values are dropped rather than
+ * serialised.
+ */
+type SafeLogValue = string | number | boolean | null;
+/**
+ * Filters an arbitrary field bag down to the fields that are safe to log.
+ *
+ * Created by {@link createSafeLogFields}.
+ */
+type SafeLogFields = (fields?: Record<string, unknown>) => Record<string, SafeLogValue>;
+/**
+ * Emits one structured, allowlisted log event.
+ *
+ * Created by {@link createLogEvent}.
+ */
+type LogEvent = (level: LogLevel, event: string, fields?: Record<string, unknown>) => void;
+/**
+ * The subset of `console` a {@link LogEvent} writes to. Injectable so the
+ * privacy behaviour can be asserted in tests.
+ */
+interface LogSink {
+  info: (...args: readonly unknown[]) => void;
+  warn: (...args: readonly unknown[]) => void;
+  error: (...args: readonly unknown[]) => void;
+}
+/**
+ * Options for {@link createLogEvent}.
+ */
+interface LogEventOptions {
+  /** Prefix written before the payload, e.g. `'[my-app]'`. */
+  prefix: string;
+  /** Allowlist to apply. Defaults to `createSafeLogFields()`. */
+  safeLogFields: SafeLogFields;
+  /** Where lines are written. Defaults to the global `console`. */
+  sink: LogSink;
+}
+/**
+ * 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', ...])`.
+ */
+declare const BASE_ALLOWED_LOG_KEYS: readonly string[];
+/**
+ * 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 }
+ */
+declare function createSafeLogFields(extraAllowedKeys?: readonly string[]): SafeLogFields;
+/**
+ * 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'
+ */
+declare function errorName(error: unknown): string;
+/**
+ * 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 }
+ */
+declare function createLogEvent(options?: Partial<LogEventOptions>): LogEvent;
+/**
+ * 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) });
+ */
+declare const logEvent: LogEvent;
+//#endregion
+//#region src/core/observability/readiness.d.ts
+/**
+ * One named configuration check.
+ */
+interface ReadinessCheck {
+  /** Stable machine-readable check name, e.g. `'fanvue_oauth'`. */
+  name: string;
+  /** Whether the check passes. */
+  ready: boolean;
+  /** Why it fails, or `null` when it passes. Never contains a secret value. */
+  detail: string | null;
+}
+/** The environment shape the checks read, so `process.env` is never read directly. */
+type ReadinessEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * 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 });
+ */
+declare function configurationReadiness(env?: ReadinessEnv): readonly ReadinessCheck[];
+//#endregion
+//#region src/core/observability/sentry-scrubber.d.ts
+/**
+ * A `beforeSend`-compatible scrubber.
+ *
+ * Generic in the event type so it satisfies Sentry's `beforeSend` option
+ * without this package importing `@sentry/*` — the returned function is
+ * structurally assignable to `(event, hint) => event | null`.
+ */
+type SentryScrubber = <T>(event: T) => T;
+/**
+ * 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.
+ */
+declare const BASE_SENSITIVE_KEY_PATTERN: RegExp;
+/**
+ * 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),
+ * });
+ */
+declare function createSentryScrubber(extraSensitiveKeyPattern?: RegExp | null): SentryScrubber;
+//#endregion
+export { DEFAULT_ISSUER_URL as $, resetFanvueEnvCache as $t, safeJsonParse as A, isUnpublishResultMessage as At, refreshAccessToken as B, FanvueStringListErrorBodySchema as Bt, requireMachineAuth as C, UNPUBLISH_RESULT_MESSAGE as Ct, FanvueUserSchema as D, UnpublishResultMessageSchema as Dt, AuthorizeOnBehalfResponseSchema as E, UnpublishResultMessage as Et, requestAuthorizationCodeOnBehalf as F, FanvueErrorBody as Ft, JsonParseError as G, parseFanvueErrorBody as Gt, EmbeddedAuthConfig as H, NormalisedFanvueError as Ht, createSessionJwt as I, FanvueErrorBodySchema as It, SessionPayload as J, FanvueEnvSchema as Jt, OAuthConfig as K, EnvSource as Kt, verifySessionJwt as L, FanvueErrorFieldBodySchema as Lt, exchangeSessionToken as M, AppErrorEnvelopeSchema as Mt, getSessionTokenFromUrl as N, FANVUE_APP_ERROR_CODES as Nt, SessionPayloadSchema as O, isFanvueOrigin as Ot, getThemeFromUrl as P, FanvueAppErrorCode as Pt, DEFAULT_API_BASE_URL as Q, parseFanvueEnv as Qt, createAuthorizationUrl as R, FanvueIssueListErrorBodySchema as Rt, boundedBatchSize as S, UNPUBLISH_REQUEST_MESSAGE as St, createFanvueClient as T, UnpublishRequestMessageSchema as Tt, EmbeddedAuthError as U, OAuthErrorBody as Ut, ApiError as V, NON_SESSION_401_CODES as Vt, FanvueUser as W, OAuthErrorBodySchema as Wt, TokenResponse as X, flagEnabled as Xt, SessionVerifyError as Y, fanvueEnv as Yt, API_VERSION as Z, isFanvueConfigured as Zt, logEvent as _, PUBLISH_RESULT_MESSAGE as _t, ReadinessEnv as a, FanvueAccessMode as an, HybridPaginationSchema as at, MachineAuthResult as b, PublishResultMessage as bt, LogEvent as c, BEARER_PREFIX as cn, OffsetPaginationSchema as ct, LogSink as d, offsetPageSchema as dt, EXPERIENCE_DENIAL_REASONS as en, DEFAULT_PLATFORM_URL as et, SafeLogFields as f, EXPERIENCE_MESSAGE_TYPES as ft, errorName as g, PUBLISH_REQUEST_MESSAGE as gt, createSafeLogFields as h, ExperienceMessageType as ht, ReadinessCheck as i, FANVUE_ACCESS_MODES as in, HybridPagination as it, FanvueTheme as j, AppErrorEnvelope as jt, TokenResponseSchema as k, isPublishResultMessage as kt, LogEventOptions as l, HEADER_UPDATED_SESSION as ln, clampPageSize as lt, createLogEvent as m, ExperienceMessageSchema as mt, SentryScrubber as n, ExperienceDenialReason as nn, assertFanvueDomain as nt, configurationReadiness as o, FanvueAccessModeSchema as on, MAX_PAGE_SIZE as ot, SafeLogValue as p, ExperienceMessage as pt, OAuthError as q, FanvueEnv as qt, createSentryScrubber as r, ExperienceEntitledReason as rn, DEFAULT_PAGE_SIZE as rt, BASE_ALLOWED_LOG_KEYS as s, accessModeFromDenialReason as sn, OffsetPagination as st, BASE_SENSITIVE_KEY_PATTERN as t, EXPERIENCE_ENTITLED_REASONS as tn, DEFAULT_SCOPES as tt, LogLevel as u, cursorPageSchema as ut, MINIMUM_BEARER_SECRET_LENGTH as v, PublishRequestMessage as vt, FanvueClient as w, UnpublishRequestMessage as wt, SignedRequestVerifier as x, PublishResultMessageSchema as xt, MachineAuthOptions as y, PublishRequestMessageSchema as yt, exchangeCodeForToken as z, FanvueMessageErrorBodySchema as zt };
+//# sourceMappingURL=index-C3CXrRiw.d.ts.map