@zweer/mage-space-client 0.0.0

package/dist/index.cjs

@@ -0,0 +1,1284 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let jose = require("jose");
+//#region lib/errors.ts
+/** Typed error hierarchy for the mage.space client. */
+/** Base class for every error thrown by this library. */
+var MageSpaceError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "MageSpaceError";
+	}
+};
+/** Authentication failures (token refresh, session creation). */
+var AuthError = class extends MageSpaceError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "AuthError";
+	}
+};
+/** Action-hash discovery failures (page/chunk fetch, empty registry). */
+var DiscoveryError = class extends MageSpaceError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "DiscoveryError";
+	}
+};
+/** A Server Action returned 404, indicating a stale (post-deploy) hash. */
+var StaleActionError = class extends MageSpaceError {
+	action;
+	constructor(action, options) {
+		super(`Action "${action}" returned 404 (stale hash)`, options);
+		this.action = action;
+		this.name = "StaleActionError";
+	}
+};
+/** Failures while submitting or polling a generation job. */
+var GenerationError = class extends MageSpaceError {
+	code;
+	constructor(message, code, options) {
+		super(message, options);
+		this.code = code;
+		this.name = "GenerationError";
+	}
+};
+/** Failure to parse a React Server Component (RSC) wire response. */
+var RscParseError = class extends MageSpaceError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "RscParseError";
+	}
+};
+/** A wait/poll operation exceeded its deadline or was aborted. */
+var TimeoutError = class extends MageSpaceError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TimeoutError";
+	}
+};
+/**
+* Guard for irreversible operations: throws unless `{ confirm: true }` is passed.
+*
+* @throws {MageSpaceError} when confirmation is missing.
+*/
+function requireConfirm(action, opts) {
+	if (opts?.confirm !== true) throw new MageSpaceError(`${action} is irreversible and requires explicit confirmation: pass { confirm: true }`);
+}
+//#endregion
+//#region lib/actions.ts
+/**
+* Action-hash discovery and caching.
+*
+* mage.space's Server Action hashes change on every Vercel deploy, so the client
+* discovers them from the page's JS bundles and caches the result. The registry
+* serves hashes from a warm seed / cache and only re-discovers when a hash goes
+* stale (a request 404s) or when explicitly refreshed.
+*/
+/** `createServerReference)("<hash>", callServer, void 0, findSourceMapURL, "<fn>")` */
+const CREATE_SERVER_REF_RE = /createServerReference\)\("([0-9a-f]+)"[^)]*?"([^"]+)"\)/g;
+/** `/_next/static/chunks/....js` references in the page HTML. */
+const CHUNK_RE = /\/_next\/static\/chunks\/[^"'`()\s]+?\.js/g;
+/**
+* Default pages scraped during discovery. Server Actions are split per route, so
+* a single page misses route-specific actions (e.g. `deleteReference` lives only
+* in the `/references` bundle) — scrape the main routes and union their chunks.
+*/
+const DISCOVERY_PAGES = [
+	"/explore",
+	"/creations",
+	"/characters",
+	"/references"
+];
+/** Default in-process snapshot cache. */
+var InMemoryActionCache = class {
+	snapshot = null;
+	async load() {
+		return this.snapshot;
+	}
+	async save(snapshot) {
+		this.snapshot = snapshot;
+	}
+};
+/**
+* Discover the current Server Action hashes by scraping the page HTML for JS
+* chunk URLs and extracting `createServerReference(...)` calls from each chunk.
+*
+* @throws {DiscoveryError} on network failure or when nothing is discovered.
+*/
+async function discoverActions(opts) {
+	const { fetch, baseUrl } = opts;
+	const pages = opts.discoveryPath !== void 0 ? [opts.discoveryPath] : opts.discoveryPaths ?? DISCOVERY_PAGES;
+	let deploymentId = "";
+	const chunkPaths = /* @__PURE__ */ new Set();
+	for (const page of pages) {
+		let res;
+		try {
+			res = await fetch(`${baseUrl}${page}`, { headers: { accept: "text/html" } });
+		} catch {
+			continue;
+		}
+		if (!res.ok) continue;
+		if (deploymentId === "") deploymentId = res.headers.get("x-deployment-id") ?? "";
+		const html = await res.text();
+		for (const match of html.matchAll(CHUNK_RE)) {
+			const chunkPath = match[0];
+			if (chunkPath !== void 0) chunkPaths.add(chunkPath);
+		}
+	}
+	if (chunkPaths.size === 0) throw new DiscoveryError("No JS chunk references found in discovery pages");
+	const hashes = {};
+	await Promise.all([...chunkPaths].map(async (path) => {
+		try {
+			const chunkRes = await fetch(`${baseUrl}${path}`, { headers: { accept: "application/javascript" } });
+			if (!chunkRes.ok) return;
+			const js = await chunkRes.text();
+			for (const match of js.matchAll(CREATE_SERVER_REF_RE)) {
+				const hash = match[1];
+				const fn = match[2];
+				if (hash !== void 0 && fn !== void 0 && !(fn in hashes)) hashes[fn] = hash;
+			}
+		} catch {}
+	}));
+	if (Object.keys(hashes).length === 0) throw new DiscoveryError("No server action hashes discovered in JS chunks");
+	return {
+		deploymentId,
+		hashes,
+		discoveredAt: Date.now()
+	};
+}
+/**
+* Serves action hashes from a warm seed / pluggable cache, discovering lazily and
+* refreshing on staleness. Concurrent refreshes are de-duplicated (single-flight).
+*/
+var ActionRegistry = class {
+	fetch;
+	baseUrl;
+	cache;
+	seed;
+	discoveryPath;
+	discoveryPaths;
+	maxAgeMs;
+	snapshot = null;
+	inflight = null;
+	constructor(opts) {
+		this.fetch = opts.fetch;
+		this.baseUrl = opts.baseUrl;
+		this.cache = opts.cache ?? new InMemoryActionCache();
+		this.seed = opts.seed;
+		this.discoveryPath = opts.discoveryPath;
+		this.discoveryPaths = opts.discoveryPaths;
+		this.maxAgeMs = opts.maxAgeMs ?? 0;
+	}
+	isStale(snapshot) {
+		return this.maxAgeMs > 0 && Date.now() - snapshot.discoveredAt > this.maxAgeMs;
+	}
+	/** Return the current snapshot, loading from cache/seed or discovering as needed. */
+	async getSnapshot() {
+		if (this.snapshot !== null && !this.isStale(this.snapshot)) return this.snapshot;
+		const cached = await this.cache.load();
+		if (cached !== null && !this.isStale(cached)) {
+			this.snapshot = cached;
+			return cached;
+		}
+		if (this.seed !== void 0) {
+			this.snapshot = this.seed;
+			await this.cache.save(this.seed);
+			return this.seed;
+		}
+		return this.refresh();
+	}
+	/** Force re-discovery. Concurrent callers share one in-flight discovery. */
+	async refresh() {
+		if (this.inflight !== null) return this.inflight;
+		this.inflight = (async () => {
+			try {
+				const fresh = await discoverActions({
+					fetch: this.fetch,
+					baseUrl: this.baseUrl,
+					discoveryPath: this.discoveryPath,
+					discoveryPaths: this.discoveryPaths
+				});
+				this.snapshot = fresh;
+				await this.cache.save(fresh);
+				return fresh;
+			} finally {
+				this.inflight = null;
+			}
+		})();
+		return this.inflight;
+	}
+	/** Resolve a function name to its current hash + deployment id. */
+	async getHash(action) {
+		let snapshot = await this.getSnapshot();
+		let hash = snapshot.hashes[action];
+		if (hash === void 0) {
+			snapshot = await this.refresh();
+			hash = snapshot.hashes[action];
+		}
+		if (hash === void 0) throw new DiscoveryError(`Action "${action}" not found after discovery`);
+		return {
+			hash,
+			deploymentId: snapshot.deploymentId
+		};
+	}
+	/** Drop the cached snapshot and re-discover (called on a stale 404). */
+	async invalidate() {
+		this.snapshot = null;
+		return this.refresh();
+	}
+};
+//#endregion
+//#region lib/rsc.ts
+/**
+* Minimal parser for the React Server Component (RSC) "Flight" wire format used
+* by Next.js Server Action responses.
+*
+* The wire format is a sequence of newline-delimited rows:
+*
+* ```text
+* 0:{"a":"$@1","f":"","b":"buildId"}
+* 1:{"history_id":"e3357fb8-...","architecture_config":"$T0:0:architectureConfig"}
+* ```
+*
+* Each row is `<hexId>:<jsonPayload>`. Values may contain sentinels:
+* - `$undefined`       → `undefined`
+* - `$@<id>`           → reference to another row (a resolved promise)
+* - `$$...`            → an escaped literal string starting with `$`
+* - `$<other>`         → a typed marker (kept verbatim, best-effort)
+*
+* @remarks
+* The exact envelope for some read actions (e.g. `getHistoryById`) should be
+* confirmed against live traffic via the rev-eng Playwright flow; this parser is
+* intentionally tolerant and falls back to the last JSON row when the row-0
+* `{ a: ... }` envelope is absent.
+*/
+const REF_RE = /^\$@([0-9a-f]+)$/i;
+/** A plain row reference like `$5` (not a promise `$@5`, nor a `$D`/`$S`/... marker). */
+const HEX_REF_RE = /^\$([0-9a-f]+)$/i;
+const ROW_ID_RE = /^[0-9a-f]+$/i;
+/** Return the char index after consuming exactly `byteLen` UTF-8 bytes from `start`. */
+function endOfUtf8Slice(text, start, byteLen) {
+	let bytes = 0;
+	let i = start;
+	while (i < text.length && bytes < byteLen) {
+		const cp = text.codePointAt(i);
+		bytes += cp <= 127 ? 1 : cp <= 2047 ? 2 : cp <= 65535 ? 3 : 4;
+		i += cp > 65535 ? 2 : 1;
+	}
+	return i;
+}
+/**
+* Parse the raw Flight text into a map of `rowId → value`.
+*
+* @remarks
+* Most rows are `id:<json>\n`, but text rows are length-delimited:
+* `id:T<hexlen>,<hexlen UTF-8 bytes>` and are NOT newline-terminated — the next
+* row begins immediately after the counted bytes. A naive line split therefore
+* glues the following data row onto a multi-line prompt (which is exactly why
+* large `getHistoryPaginated` responses failed to parse). This parser is
+* position/length aware so length-delimited rows are consumed exactly and every
+* subsequent row stays isolated.
+*/
+function parseFlightRows(text) {
+	const rows = /* @__PURE__ */ new Map();
+	const n = text.length;
+	let pos = 0;
+	while (pos < n) {
+		if (text[pos] === "\n") {
+			pos += 1;
+			continue;
+		}
+		const colon = text.indexOf(":", pos);
+		if (colon === -1) break;
+		const id = text.slice(pos, colon);
+		if (!ROW_ID_RE.test(id)) {
+			const nl = text.indexOf("\n", pos);
+			if (nl === -1) break;
+			pos = nl + 1;
+			continue;
+		}
+		if (text[colon + 1] === "T") {
+			const comma = text.indexOf(",", colon + 2);
+			if (comma === -1) break;
+			const byteLen = Number.parseInt(text.slice(colon + 2, comma), 16);
+			const start = comma + 1;
+			const end = endOfUtf8Slice(text, start, byteLen);
+			rows.set(id, text.slice(start, end));
+			pos = end;
+			continue;
+		}
+		const nl = text.indexOf("\n", colon + 1);
+		const payload = nl === -1 ? text.slice(colon + 1) : text.slice(colon + 1, nl);
+		pos = nl === -1 ? n : nl + 1;
+		const first = payload[0];
+		if (first === void 0) continue;
+		if (!(first === "{" || first === "[" || first === "\"" || first === "-" || first >= "0" && first <= "9" || payload === "true" || payload === "false" || payload === "null")) continue;
+		try {
+			rows.set(id, JSON.parse(payload));
+		} catch {}
+	}
+	return rows;
+}
+/** Recursively resolve Flight sentinels/references within a parsed value. */
+function resolveFlightValue(value, rows, seen = /* @__PURE__ */ new Set()) {
+	if (typeof value === "string") {
+		if (value === "$undefined") return;
+		const ref = REF_RE.exec(value) ?? HEX_REF_RE.exec(value);
+		if (ref) {
+			const refId = ref[1];
+			if (refId === void 0 || seen.has(refId)) return;
+			seen.add(refId);
+			const target = rows.get(refId);
+			return target === void 0 ? void 0 : resolveFlightValue(target, rows, seen);
+		}
+		if (value.startsWith("$$")) return value.slice(1);
+		return value;
+	}
+	if (Array.isArray(value)) return value.map((entry) => resolveFlightValue(entry, rows, seen));
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [key, entry] of Object.entries(value)) out[key] = resolveFlightValue(entry, rows, seen);
+		return out;
+	}
+	return value;
+}
+/**
+* Parse a Server Action response and return the action's resolved return value.
+*
+* @throws {RscParseError} when the response contains no parseable rows.
+*/
+function parseServerActionResponse(text) {
+	const rows = parseFlightRows(text);
+	if (rows.size === 0) throw new RscParseError("Empty or unparseable RSC response");
+	const root = rows.get("0");
+	if (root !== null && typeof root === "object" && !Array.isArray(root) && "a" in root) return resolveFlightValue(root.a, rows);
+	let lastId = null;
+	for (const id of rows.keys()) if (lastId === null || Number.parseInt(id, 16) > Number.parseInt(lastId, 16)) lastId = id;
+	return resolveFlightValue(lastId === null ? void 0 : rows.get(lastId), rows);
+}
+/**
+* Unwrap a single-object result that some Server Actions (notably the
+* `*Parallel` family) wrap in a one-element array.
+*
+* @remarks
+* `getCreationsPaginatedParallel` and `getMentionSuggestionsParallel` return their
+* payload as `[value]` on the RSC wire (`1:["$@2"]`), whereas most actions return
+* the value directly. This normalizes object-returning actions to the value; it is
+* a no-op when the response is already the object. Do NOT use it for actions whose
+* genuine return type is an array (e.g. `getReferences`).
+*/
+function unwrapResult(value) {
+	return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+//#endregion
+//#region lib/characters.ts
+/** Character actions are served from the `/explore` page. */
+const CHARACTERS_PATH = "/explore";
+const DEFAULT_SEARCH_LIMIT = 10;
+var CharactersService = class {
+	http;
+	auth;
+	constructor(http, auth) {
+		this.http = http;
+		this.auth = auth;
+	}
+	/** Search the caller's characters (and optionally public references) by name. */
+	async search(opts) {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const body = {
+			query: opts.query,
+			uid,
+			limit: opts.limit ?? DEFAULT_SEARCH_LIMIT,
+			includePublicReferences: opts.includePublicReferences ?? false,
+			referenceModalities: opts.referenceModalities ?? ["image", "audio"]
+		};
+		const { data } = await this.http.callAction({
+			action: "getMentionSuggestionsParallel",
+			path: CHARACTERS_PATH,
+			args: [body],
+			session
+		});
+		return unwrapResult(data);
+	}
+	/** Create a new character from an already-uploaded image URL. */
+	async create(input) {
+		const session = await this.auth.getSession();
+		const body = {
+			name: input.name,
+			username: input.username,
+			image_url: input.image_url,
+			audio_url: input.audio_url ?? null,
+			description: input.description ?? null,
+			tags: input.tags ?? [],
+			visibility: input.visibility ?? "private",
+			moderation: input.moderation ?? []
+		};
+		const { data } = await this.http.callAction({
+			action: "createCharacter",
+			path: CHARACTERS_PATH,
+			args: [body],
+			session
+		});
+		return data;
+	}
+	/** Update a character's mutable fields (name, description, tags, visibility, voice). */
+	async update(id, patch) {
+		const session = await this.auth.getSession();
+		const { data } = await this.http.callAction({
+			action: "updateCharacter",
+			path: CHARACTERS_PATH,
+			args: [id, patch],
+			session
+		});
+		return data;
+	}
+	/** Soft-delete a character. */
+	async delete(id) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+	}
+	/** Fetch a single character by id; resolves to `null` when it does not exist. */
+	async get(id) {
+		const session = await this.auth.getSession();
+		const { data } = await this.http.callAction({
+			action: "getCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+		return data ?? null;
+	}
+	/** Fetch multiple characters by id in a single call. */
+	async getMany(ids) {
+		const session = await this.auth.getSession();
+		const { data } = await this.http.callAction({
+			action: "getCharacters",
+			path: CHARACTERS_PATH,
+			args: [ids],
+			session
+		});
+		return data ?? [];
+	}
+	/** Make a character public. */
+	async publish(id) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "publishCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+	}
+	/** Make a character private. */
+	async unpublish(id) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "unpublishCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+	}
+	/**
+	* Upload a character reference image (base64 data URL) and return its CDN URL.
+	*
+	* @param dataUrl - `data:image/jpeg;base64,...` (JPEG preferred; PNG/WebP ok).
+	*/
+	async uploadImage(dataUrl) {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const { data } = await this.http.callAction({
+			action: "uploadCharacterImage",
+			path: CHARACTERS_PATH,
+			args: [dataUrl, uid],
+			session
+		});
+		return data;
+	}
+	/**
+	* Browse characters with pagination.
+	*
+	* @remarks
+	* Omit `uid` to browse the public/featured feed; pass it to page through a
+	* single user's characters.
+	*/
+	async listPaginated(opts = {}) {
+		const session = await this.auth.getSession();
+		const limit = opts.limit ?? 100;
+		const offset = opts.offset ?? 0;
+		const filters = {};
+		if (opts.uid !== void 0) filters.uid = opts.uid;
+		if (opts.visibility !== void 0) filters.visibility = opts.visibility;
+		if (opts.modality !== void 0) filters.modality = opts.modality;
+		if (opts.featured !== void 0) filters.featured = opts.featured;
+		const { data } = await this.http.callAction({
+			action: "getCharactersPaginated",
+			path: CHARACTERS_PATH,
+			args: [
+				limit,
+				offset,
+				filters
+			],
+			session
+		});
+		return data;
+	}
+	/**
+	* Generate a voice for a character from its reference image.
+	*
+	* @remarks Costs gems (not covered by the unlimited tier).
+	* @experimental Request body inferred from JS bundle; not yet verified live.
+	*/
+	async generateVoice(opts) {
+		const [authToken, session] = await Promise.all([this.auth.getIdToken(), this.auth.getSession()]);
+		const { data } = await this.http.callAction({
+			action: "generateCharacterVoice",
+			path: CHARACTERS_PATH,
+			args: [{
+				imageUrl: opts.imageUrl,
+				guidancePrompt: opts.guidancePrompt ?? ""
+			}, authToken],
+			session
+		});
+		return data;
+	}
+	/**
+	* Follow a (public) character.
+	*
+	* @experimental Request body inferred from JS bundle; not yet verified live.
+	*/
+	async follow(id) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "followCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+	}
+	/**
+	* Unfollow a character.
+	*
+	* @experimental Request body inferred from JS bundle; not yet verified live.
+	*/
+	async unfollow(id) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "unfollowCharacter",
+			path: CHARACTERS_PATH,
+			args: [id],
+			session
+		});
+	}
+};
+//#endregion
+//#region lib/auth.ts
+/**
+* Firebase authentication: refresh token → ID token → session cookie.
+*
+* The refresh token is the only long-lived credential the caller supplies.
+* From it we mint a Firebase ID token (~1h) via the Secure Token REST API, and
+* exchange that for a `__session` cookie (~24h) via the `createUserSession`
+* Server Action. Both are cached and refreshed 5 minutes before expiry.
+*/
+const DEFAULT_FIREBASE_API_KEY = "AIzaSyAzUV2NNUOlLTL04jwmUw9oLhjteuv6Qr4";
+const SECURE_TOKEN_URL = "https://securetoken.googleapis.com/v1/token";
+const EXPIRY_BUFFER_MS = 3e5;
+const SESSION_DEFAULT_TTL_MS = 864e5;
+const ID_TOKEN_DEFAULT_TTL_S = 3600;
+var AuthManager = class {
+	refreshToken;
+	http;
+	fetchImpl;
+	apiKey;
+	sessionPath;
+	tokens = null;
+	session = null;
+	constructor(opts) {
+		this.refreshToken = opts.refreshToken;
+		this.http = opts.http;
+		this.fetchImpl = opts.fetch;
+		this.apiKey = opts.firebaseApiKey ?? DEFAULT_FIREBASE_API_KEY;
+		this.sessionPath = opts.sessionPath ?? "/creations";
+	}
+	/** Return a valid Firebase ID token, refreshing via the refresh token if needed. */
+	async getIdToken() {
+		if (this.tokens !== null && Date.now() < this.tokens.expiresAt - EXPIRY_BUFFER_MS) return this.tokens.idToken;
+		return (await this.refreshTokens()).idToken;
+	}
+	/** Return the Firebase uid (fetching an ID token first if necessary). */
+	async getUserId() {
+		if (this.tokens !== null) return this.tokens.userId;
+		return (await this.refreshTokens()).userId;
+	}
+	/** Return a valid `__session` cookie, creating one via `createUserSession` if needed. */
+	async getSession() {
+		if (this.session !== null && Date.now() < this.session.expiresAt - EXPIRY_BUFFER_MS) return this.session.cookie;
+		const idToken = await this.getIdToken();
+		const cookie = extractSessionCookie((await this.http.callAction({
+			action: "createUserSession",
+			path: this.sessionPath,
+			args: [idToken]
+		})).headers);
+		if (cookie === null) throw new AuthError("createUserSession did not return a __session cookie");
+		const expiresAt = jwtExpiryMs(cookie) ?? Date.now() + SESSION_DEFAULT_TTL_MS;
+		this.session = {
+			cookie,
+			expiresAt
+		};
+		return cookie;
+	}
+	async refreshTokens() {
+		const body = new URLSearchParams({
+			grant_type: "refresh_token",
+			refresh_token: this.refreshToken
+		});
+		const res = await this.fetchImpl(`${SECURE_TOKEN_URL}?key=${this.apiKey}`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: body.toString()
+		});
+		if (!res.ok) throw new AuthError(`Token refresh failed: HTTP ${res.status} (refresh token may be invalid or revoked)`);
+		const json = await res.json();
+		if (json.id_token === void 0 || json.user_id === void 0) throw new AuthError("Token refresh response missing id_token/user_id");
+		if (json.refresh_token !== void 0) this.refreshToken = json.refresh_token;
+		const ttlS = json.expires_in === void 0 ? ID_TOKEN_DEFAULT_TTL_S : Number(json.expires_in);
+		const expiresAt = jwtExpiryMs(json.id_token) ?? Date.now() + ttlS * 1e3;
+		this.tokens = {
+			idToken: json.id_token,
+			refreshToken: this.refreshToken,
+			userId: json.user_id,
+			expiresAt
+		};
+		return this.tokens;
+	}
+};
+/** Read the `exp` claim (ms) from a JWT, or `null` if it cannot be decoded. */
+function jwtExpiryMs(jwt) {
+	try {
+		const { exp } = (0, jose.decodeJwt)(jwt);
+		return typeof exp === "number" ? exp * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+/** Extract the `__session` value from a `Set-Cookie` response header. */
+function extractSessionCookie(headers) {
+	const withGetSetCookie = headers;
+	const list = typeof withGetSetCookie.getSetCookie === "function" ? withGetSetCookie.getSetCookie() : headers.get("set-cookie") !== null ? [headers.get("set-cookie")] : [];
+	for (const cookie of list) {
+		const match = /(?:^|;\s*)__session=([^;]+)/.exec(cookie);
+		if (match !== null && match[1] !== void 0) return match[1];
+	}
+	return null;
+}
+//#endregion
+//#region lib/generation.ts
+/** Generation actions are served from the `/explore` page. */
+const GENERATION_PATH = "/explore";
+/** RSC sentinel for an absent value. */
+const UNDEFINED$1 = "$undefined";
+/** Default concept id for mango-v3-pro (from docs — verify per model via rev-eng). */
+const DEFAULT_CONCEPT_ID = "0cd8c7ed2e554d0f98f20c8cf8c0f7c";
+/** Default concept id for berry-2 video (from docs — verify per model via rev-eng). */
+const DEFAULT_BERRY_CONCEPT_ID = "0b1fa74f7347406392422d24f2885684";
+const DEFAULT_POLL_INTERVAL_MS = 4e3;
+const DEFAULT_TIMEOUT_MS = 3e5;
+var GenerationService = class {
+	http;
+	auth;
+	constructor(http, auth) {
+		this.http = http;
+		this.auth = auth;
+	}
+	/** Submit an image generation job and return its `historyId`. */
+	async submit(opts) {
+		const config = {
+			seed: opts.seed ?? null,
+			prompt: opts.prompt,
+			model_id: opts.model ?? "mango-v3-pro",
+			fast_mode: opts.fastMode ?? false,
+			resolution: opts.resolution ?? "1K",
+			architecture: opts.architecture ?? "mango",
+			aspect_ratio: opts.aspectRatio ?? "portrait",
+			image: opts.image ?? UNDEFINED$1,
+			additional_images: opts.additionalImages ?? [],
+			characters: mapCharacters(opts.characters),
+			references: mapCharacters(opts.references),
+			audio_references: [],
+			moodboard: UNDEFINED$1
+		};
+		return this.runArchitecture(config, opts.conceptId ?? DEFAULT_CONCEPT_ID, opts.generationMode);
+	}
+	/** Submit a video generation job (Berry-2 family) and return its `historyId`. */
+	async submitVideo(opts) {
+		const config = {
+			seed: opts.seed ?? null,
+			prompt: opts.prompt,
+			model_id: opts.model ?? "berry-2",
+			fast_mode: opts.fastMode ?? false,
+			resolution: opts.resolution ?? "480p",
+			architecture: opts.architecture ?? "berry",
+			berry_aspect_ratio: opts.aspectRatio ?? "9:16",
+			duration: opts.duration ?? "3",
+			image: opts.image ?? UNDEFINED$1,
+			additional_images: opts.additionalImages ?? [],
+			characters: mapCharacters(opts.characters),
+			references: mapCharacters(opts.references),
+			audio_references: []
+		};
+		return this.runArchitecture(config, opts.conceptId ?? DEFAULT_BERRY_CONCEPT_ID, opts.generationMode);
+	}
+	/** Shared `runArchitecture` call for image and video configs. */
+	async runArchitecture(config, conceptId, generationMode = "unlimited") {
+		const [authToken, session] = await Promise.all([this.auth.getIdToken(), this.auth.getSession()]);
+		const args = [{
+			architectureConfig: config,
+			architectureConfigToSave: "$0:0:architectureConfig",
+			authToken,
+			conceptId,
+			activePowerPack: null,
+			generationMode
+		}];
+		const { data } = await this.http.callAction({
+			action: "runArchitecture",
+			path: GENERATION_PATH,
+			args,
+			session
+		});
+		if (data !== null && typeof data === "object" && "error_code" in data) {
+			const code = Number(data.error_code);
+			throw new GenerationError(errorMessageForCode(code), code);
+		}
+		const historyId = data !== null && typeof data === "object" ? data.history_id : void 0;
+		if (typeof historyId !== "string") throw new GenerationError("runArchitecture did not return a history_id");
+		return { historyId };
+	}
+	/** Fetch a single history record by id. */
+	async getHistory(historyId) {
+		const session = await this.auth.getSession();
+		const { data } = await this.http.callAction({
+			action: "getHistoryById",
+			path: GENERATION_PATH,
+			args: [historyId],
+			session
+		});
+		return data;
+	}
+	/** Cancel a running generation job. */
+	async cancelJob(historyId) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "cancelArchitectureJob",
+			path: GENERATION_PATH,
+			args: [historyId],
+			session
+		});
+	}
+	/** Poll until the job leaves the `running` state, returning the final record. */
+	async waitForResult(historyId, opts = {}) {
+		const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+		const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		const deadline = Date.now() + timeoutMs;
+		for (;;) {
+			if (opts.signal?.aborted === true) throw new TimeoutError("waitForResult was aborted");
+			const item = await this.getHistory(historyId);
+			if (item.status === "success") return item;
+			if (item.status === "error") throw new GenerationError(`Generation failed: ${JSON.stringify(item.error ?? null)}`);
+			if (Date.now() > deadline) throw new TimeoutError(`Generation timed out after ${timeoutMs}ms (last status: ${item.status})`);
+			await delay(intervalMs, opts.signal);
+		}
+	}
+};
+function delay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			reject(new TimeoutError("waitForResult was aborted"));
+		}, { once: true });
+	});
+}
+/** Normalize characters for an `architectureConfig`, defaulting absent audio to the RSC sentinel. */
+function mapCharacters(characters = []) {
+	return characters.map((c) => ({
+		id: c.id,
+		name: c.name,
+		username: c.username,
+		image_url: c.image_url,
+		audio_url: c.audio_url ?? UNDEFINED$1
+	}));
+}
+function errorMessageForCode(code) {
+	switch (code) {
+		case 400: return "Bad request (wrong generationMode for your subscription tier?)";
+		case 401: return "Authentication failed (token expired or invalid)";
+		case 403: return "User is banned";
+		case 4031: return "Prompt blocked by content moderation";
+		default: return `Generation error (code ${code})`;
+	}
+}
+//#endregion
+//#region lib/history.ts
+/** History actions are served from the `/creations` page. */
+const HISTORY_PATH = "/creations";
+const DEFAULT_LIMIT = 10;
+/** RSC sentinel for an absent value. */
+const UNDEFINED = "$undefined";
+var HistoryService = class {
+	http;
+	auth;
+	constructor(http, auth) {
+		this.http = http;
+		this.auth = auth;
+	}
+	/** List generation history for the authenticated user. */
+	async list(opts = {}) {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const limit = opts.limit ?? DEFAULT_LIMIT;
+		const offset = opts.offset ?? 0;
+		const filters = {
+			status: opts.status === "all" ? UNDEFINED : opts.status ?? "success",
+			type: UNDEFINED
+		};
+		const { data } = await this.http.callAction({
+			action: "getHistoryPaginated",
+			path: HISTORY_PATH,
+			args: [
+				uid,
+				limit,
+				offset,
+				filters
+			],
+			session
+		});
+		return unwrapResult(data);
+	}
+	/** List the user's permanently saved creations. */
+	async listCreations(opts = {}) {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const limit = opts.limit ?? DEFAULT_LIMIT;
+		const offset = opts.offset ?? 0;
+		const { data } = await this.http.callAction({
+			action: "getCreationsPaginatedParallel",
+			path: HISTORY_PATH,
+			args: [
+				uid,
+				limit,
+				offset
+			],
+			session
+		});
+		return unwrapResult(data);
+	}
+	/**
+	* Save a completed generation result as a permanent creation.
+	*
+	* @param result - the `result` object of a completed history item.
+	* @remarks The API returns no body; call {@link listCreations} to retrieve the
+	* saved creation.
+	*/
+	async saveCreation(result) {
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "saveCreation",
+			path: HISTORY_PATH,
+			args: [result],
+			session
+		});
+	}
+	/**
+	* Permanently delete a history item. Irreversible — requires `{ confirm: true }`.
+	*/
+	async deleteHistory(historyId, opts) {
+		requireConfirm("deleteHistory", opts);
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteHistory",
+			path: HISTORY_PATH,
+			args: [historyId],
+			session
+		});
+	}
+	/**
+	* Permanently delete many history items. Irreversible — requires `{ confirm: true }`.
+	*
+	* @experimental Request body inferred from JS bundle; not yet verified live.
+	*/
+	async deleteManyHistories(historyIds, opts) {
+		requireConfirm("deleteManyHistories", opts);
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteManyHistories",
+			path: HISTORY_PATH,
+			args: [historyIds],
+			session
+		});
+	}
+	/**
+	* Permanently delete a saved creation. Irreversible — requires `{ confirm: true }`.
+	*/
+	async deleteCreation(creationId, opts) {
+		requireConfirm("deleteCreation", opts);
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteCreation",
+			path: HISTORY_PATH,
+			args: [creationId],
+			session
+		});
+	}
+	/**
+	* Permanently delete many creations. Irreversible — requires `{ confirm: true }`.
+	*
+	* @experimental Request body inferred from JS bundle; not yet verified live.
+	*/
+	async deleteManyCreations(creationIds, opts) {
+		requireConfirm("deleteManyCreations", opts);
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteManyCreations",
+			path: HISTORY_PATH,
+			args: [creationIds],
+			session
+		});
+	}
+};
+//#endregion
+//#region lib/http.ts
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+var HttpClient = class {
+	registry;
+	fetchImpl;
+	baseUrl;
+	userAgent;
+	constructor(registry, fetchImpl, baseUrl, userAgent = DEFAULT_USER_AGENT) {
+		this.registry = registry;
+		this.fetchImpl = fetchImpl;
+		this.baseUrl = baseUrl;
+		this.userAgent = userAgent;
+	}
+	async callAction(params, retried = false) {
+		const { hash, deploymentId } = await this.registry.getHash(params.action);
+		const headers = {
+			accept: "text/x-component",
+			"content-type": "text/plain;charset=UTF-8",
+			"next-action": hash,
+			"x-deployment-id": deploymentId,
+			origin: this.baseUrl,
+			referer: `${this.baseUrl}${params.path}`,
+			"user-agent": this.userAgent
+		};
+		if (params.session !== void 0) headers.cookie = `__session=${params.session}`;
+		const res = await this.fetchImpl(`${this.baseUrl}${params.path}`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(params.args)
+		});
+		if (res.status === 404 && !retried) {
+			await this.registry.invalidate();
+			return this.callAction(params, true);
+		}
+		if (!res.ok) {
+			const body = await safeText(res);
+			const suffix = body.length > 0 ? ` — ${body.slice(0, 200)}` : "";
+			throw new MageSpaceError(`Action "${params.action}" failed: HTTP ${res.status}${suffix}`);
+		}
+		return {
+			data: parseServerActionResponse(await res.text()),
+			headers: res.headers,
+			deploymentId: res.headers.get("x-deployment-id") ?? deploymentId
+		};
+	}
+};
+async function safeText(res) {
+	try {
+		return await res.text();
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region lib/references.ts
+/** Reference actions are served from the `/explore` page. */
+const REFERENCES_PATH = "/explore";
+const DEFAULT_PAGE_LIMIT = 20;
+var ReferencesService = class {
+	http;
+	auth;
+	constructor(http, auth) {
+		this.http = http;
+		this.auth = auth;
+	}
+	/**
+	* Upload a reference image (base64 data URL) and return its CDN URL.
+	*
+	* @param dataUrl - `data:image/jpeg;base64,...` (JPEG preferred; PNG/WebP ok).
+	*/
+	async uploadImage(dataUrl) {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const { data } = await this.http.callAction({
+			action: "uploadReferenceImage",
+			path: REFERENCES_PATH,
+			args: [dataUrl, uid],
+			session
+		});
+		return data;
+	}
+	/** Create a reusable reference from an uploaded image/audio URL. */
+	async create(input) {
+		const session = await this.auth.getSession();
+		const body = {
+			name: input.name,
+			username: input.username,
+			image_url: input.image_url,
+			audio_url: input.audio_url ?? null,
+			modality: input.modality ?? "image",
+			variant: input.variant ?? "reference",
+			description: input.description ?? null,
+			tags: input.tags ?? [],
+			visibility: input.visibility ?? "private",
+			moderation: input.moderation ?? []
+		};
+		const { data } = await this.http.callAction({
+			action: "createReference",
+			path: REFERENCES_PATH,
+			args: [body],
+			session
+		});
+		return data;
+	}
+	/** Update a reference's mutable fields (name, description, tags, visibility). */
+	async update(id, patch) {
+		const session = await this.auth.getSession();
+		const { data } = await this.http.callAction({
+			action: "updateReference",
+			path: REFERENCES_PATH,
+			args: [id, patch],
+			session
+		});
+		return data;
+	}
+	/**
+	* Permanently delete a reference (soft-delete). Irreversible — requires
+	* `{ confirm: true }`.
+	*/
+	async delete(id, opts) {
+		requireConfirm("deleteReference", opts);
+		const session = await this.auth.getSession();
+		await this.http.callAction({
+			action: "deleteReference",
+			path: REFERENCES_PATH,
+			args: [id],
+			session
+		});
+	}
+	/** List the caller's own references for a given modality (default `image`). */
+	async list(modality = "image") {
+		const [uid, session] = await Promise.all([this.auth.getUserId(), this.auth.getSession()]);
+		const { data } = await this.http.callAction({
+			action: "getReferences",
+			path: REFERENCES_PATH,
+			args: [uid, modality],
+			session
+		});
+		return data ?? [];
+	}
+	/**
+	* Browse references with pagination.
+	*
+	* @remarks
+	* Omit `uid` to browse the public/featured feed; pass it to page through a
+	* single user's references.
+	*/
+	async listPaginated(opts = {}) {
+		const session = await this.auth.getSession();
+		const limit = opts.limit ?? DEFAULT_PAGE_LIMIT;
+		const offset = opts.offset ?? 0;
+		const filters = {
+			visibility: opts.visibility ?? "public",
+			orderBy: opts.orderBy ?? "top",
+			featuredOnly: opts.featuredOnly ?? false,
+			modality: opts.modality ?? "image"
+		};
+		if (opts.uid !== void 0) filters.uid = opts.uid;
+		const { data } = await this.http.callAction({
+			action: "getReferencesPaginated",
+			path: REFERENCES_PATH,
+			args: [
+				limit,
+				offset,
+				filters
+			],
+			session
+		});
+		return data;
+	}
+};
+//#endregion
+//#region lib/seed.ts
+/**
+* Bundled action-hash snapshot from the mage.space Vercel deploy discovered on
+* 2026-08-06 (`docs/api/actions.md`).
+*
+* @remarks
+* Used as a warm seed so the very first call does not pay the discovery cost.
+* Hashes change on every deploy; when one goes stale the client re-discovers
+* automatically (404 → invalidate → refresh).
+*/
+const SEED_SNAPSHOT = {
+	deploymentId: "dpl_GLUqzVNVADQR5wogKksDvu1m3BdH",
+	discoveredAt: Date.parse("2026-08-06T00:00:00.000Z"),
+	hashes: {
+		createUserSession: "60fa7da54d8662813645f7077455339d23096f391c",
+		deleteUserSession: "0077c71a228d26498d446a89e60ec6d17199443f9e",
+		getUserHydrationData: "40314a83b96c226af04a264d1e076a06dbf3cc73b2",
+		runArchitecture: "402c09c1b4694e5bb273a949a41a2f36ca82eff394",
+		getHistoryById: "40b894a9a39b33b79d4eb046e4beeed7b30b21a887",
+		cancelArchitectureJob: "40e4b91be4f6698821f96021adaf305a74b32af2a1",
+		getHistoryPaginated: "787d245f6320977164c554a189a4d5b80c18ca3347",
+		getMentionSuggestionsParallel: "7f1553e5f697d614a2982a5400edae73c4ef672ece",
+		createCharacter: "4012fee65f53db4fbe9d83808da2869751fe503a87",
+		updateCharacter: "60dc4b95918a5fea7b2752bedebb38e0950e19a17e",
+		deleteCharacter: "40656ebd70a3804b5c18740913c8b769d4c72e1298",
+		getCharacter: "40b1e8e090a726985d8868f145865a3b5bde0803b1",
+		getCharacters: "402ea21b03340cd20f55ea8c15f56dbbc1ce957f51",
+		publishCharacter: "409a73d2187553e2e069493147969c46d7329a7c44",
+		unpublishCharacter: "40f009e2c220d4efc54b9f8968ab37e74cb66de982",
+		uploadCharacterImage: "60869f48fe83aa95969a6549f84023c9e115ee274f",
+		uploadReferenceImage: "606ba2b0eb79bd8f28c609706a89b52e0d9f517fa6",
+		createReference: "406d91cfd5589042bd72defa1071bc7c3fb84810c4",
+		updateReference: "602d6bb3ba2609661f07330224f6fd075e7af6bc9e",
+		deleteReference: "409dd73e6daafe43b500b0c9f012a33fc5350af196",
+		getReferences: "60a0357a926bc3e4031c00e62ca815e3ea21b3eb35",
+		getReferencesPaginated: "7069d599ab890e353b790d46df56160d5c0a85348a",
+		getCharactersPaginated: "7085cf87746975cbec2868405a026e22b97a20cfb4",
+		getCreationsPaginatedParallel: "7f7f533eb9fc5a3fca55cb5e19d45532a27eb75f38",
+		deleteHistory: "40e1f88b6813c101c03e136e4d5f5fadeb9909ee52",
+		deleteManyHistories: "402a5bddb2a41165f2f64782b85b4915e63ec2a849",
+		deleteCreation: "407e9ce3d04c7274e3341bf8450633dc8e3935ec9c",
+		deleteManyCreations: "403d071e9dc36382b3efff80470e6d76b3edd299b8",
+		saveCreation: "6087f655eaef4de56a01fb6c6a84df58cea0632e5f",
+		generateCharacterVoice: "6052462e345ee9878d5c36c2a160ea1873919c2b41",
+		followCharacter: "402d9d8cf924262612f29b5ef3d1a6a97d3a0a9d7a",
+		unfollowCharacter: "40842140a2e9467f854870c6ad20e3dcf17bece652"
+	}
+};
+//#endregion
+//#region lib/client.ts
+/**
+* {@link MageSpaceClient} — the public facade that wires together action
+* discovery, authentication, generation, and history.
+*/
+const DEFAULT_BASE_URL = "https://www.mage.space";
+var MageSpaceClient = class {
+	registry;
+	auth;
+	generationService;
+	historyService;
+	/** Character management (search, CRUD, pagination, uploads). */
+	characters;
+	/** Reference asset management (upload, create, update, list, feed). */
+	references;
+	constructor(options) {
+		if (!options.refreshToken) throw new Error("MageSpaceClient requires a refreshToken");
+		const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+		this.registry = new ActionRegistry({
+			fetch: fetchImpl,
+			baseUrl,
+			cache: options.cache,
+			seed: options.seed ?? SEED_SNAPSHOT
+		});
+		const http = new HttpClient(this.registry, fetchImpl, baseUrl, options.userAgent);
+		this.auth = new AuthManager({
+			refreshToken: options.refreshToken,
+			http,
+			fetch: fetchImpl,
+			firebaseApiKey: options.firebaseApiKey
+		});
+		this.generationService = new GenerationService(http, this.auth);
+		this.historyService = new HistoryService(http, this.auth);
+		this.characters = new CharactersService(http, this.auth);
+		this.references = new ReferencesService(http, this.auth);
+	}
+	/** Submit a generation job; returns its `historyId`. */
+	generate(options) {
+		return this.generationService.submit(options);
+	}
+	/** Submit a video generation job (Berry-2 family); returns its `historyId`. */
+	generateVideo(options) {
+		return this.generationService.submitVideo(options);
+	}
+	/** Fetch the current state of a generation by id. */
+	getResult(historyId) {
+		return this.generationService.getHistory(historyId);
+	}
+	/** Poll until a generation finishes (or fails / times out). */
+	waitForResult(historyId, options) {
+		return this.generationService.waitForResult(historyId, options);
+	}
+	/** Cancel a running generation job. */
+	cancelJob(historyId) {
+		return this.generationService.cancelJob(historyId);
+	}
+	/** List past generations for the authenticated user. */
+	listHistory(options) {
+		return this.historyService.list(options);
+	}
+	/** List the user's permanently saved creations. */
+	listCreations(options) {
+		return this.historyService.listCreations(options);
+	}
+	/** Save a completed generation result as a permanent creation. */
+	saveCreation(result) {
+		return this.historyService.saveCreation(result);
+	}
+	/** Permanently delete a history item. Irreversible — requires `{ confirm: true }`. */
+	deleteHistory(historyId, options) {
+		return this.historyService.deleteHistory(historyId, options);
+	}
+	/** Permanently delete many history items. Irreversible — requires `{ confirm: true }`. */
+	deleteManyHistories(historyIds, options) {
+		return this.historyService.deleteManyHistories(historyIds, options);
+	}
+	/** Permanently delete a saved creation. Irreversible — requires `{ confirm: true }`. */
+	deleteCreation(creationId, options) {
+		return this.historyService.deleteCreation(creationId, options);
+	}
+	/** Permanently delete many creations. Irreversible — requires `{ confirm: true }`. */
+	deleteManyCreations(creationIds, options) {
+		return this.historyService.deleteManyCreations(creationIds, options);
+	}
+	/** Force re-discovery of the Server Action hashes. */
+	refreshActions() {
+		return this.registry.refresh();
+	}
+};
+//#endregion
+//#region lib/index.ts
+/** Public entry point for `@zweer/mage-space-client`. */
+const VERSION = "0.0.0";
+//#endregion
+exports.ActionRegistry = ActionRegistry;
+exports.AuthError = AuthError;
+exports.CharactersService = CharactersService;
+exports.DiscoveryError = DiscoveryError;
+exports.GenerationError = GenerationError;
+exports.InMemoryActionCache = InMemoryActionCache;
+exports.MageSpaceClient = MageSpaceClient;
+exports.MageSpaceError = MageSpaceError;
+exports.ReferencesService = ReferencesService;
+exports.RscParseError = RscParseError;
+exports.SEED_SNAPSHOT = SEED_SNAPSHOT;
+exports.StaleActionError = StaleActionError;
+exports.TimeoutError = TimeoutError;
+exports.VERSION = VERSION;
+exports.discoverActions = discoverActions;
+exports.parseFlightRows = parseFlightRows;
+exports.parseServerActionResponse = parseServerActionResponse;
+exports.resolveFlightValue = resolveFlightValue;
+exports.unwrapResult = unwrapResult;