@zweer/mage-space-client 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,800 @@
+//#region lib/types.d.ts
+/**
+ * Shared type definitions for the mage.space client.
+ *
+ * @remarks
+ * mage.space is not a REST API: it uses Next.js Server Actions. These types model
+ * the request/response shapes reverse-engineered in `docs/api/*.md`.
+ */
+/** Minimal `fetch` signature the client depends on (injectable for tests). */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** In-memory representation of the Firebase token chain. */
+interface AuthTokens {
+  /** Firebase ID token (JWT), ~1h lifetime — used as `authToken` in bodies. */
+  idToken: string;
+  /** Long-lived refresh token (rotated on each refresh). */
+  refreshToken: string;
+  /** Firebase user id (uid). */
+  userId: string;
+  /** Epoch ms at which `idToken` expires. */
+  expiresAt: number;
+}
+/** Firebase session cookie state (`__session`). */
+interface SessionState {
+  /** The raw `__session` cookie value (a Firebase session JWT). */
+  cookie: string;
+  /** Epoch ms at which the session cookie expires (~24h). */
+  expiresAt: number;
+}
+/** Server Action function names the client relies on for the MVP surface. */
+type ActionName = 'createUserSession' | 'deleteUserSession' | 'getUserHydrationData' | 'runArchitecture' | 'getHistoryById' | 'cancelArchitectureJob' | 'getHistoryPaginated' | 'getMentionSuggestionsParallel' | 'createCharacter' | 'updateCharacter' | 'deleteCharacter' | 'getCharacter' | 'getCharacters' | 'publishCharacter' | 'unpublishCharacter' | 'uploadCharacterImage' | 'uploadReferenceImage' | 'createReference' | 'updateReference' | 'deleteReference' | 'getReferences' | 'getReferencesPaginated' | 'getCharactersPaginated' | 'getCreationsPaginatedParallel' | 'deleteHistory' | 'deleteManyHistories' | 'deleteCreation' | 'deleteManyCreations' | 'saveCreation' | 'generateCharacterVoice' | 'followCharacter' | 'unfollowCharacter';
+/** Map of Server Action function name → hex action hash. */
+type ActionHashes = Record<string, string>;
+/** A discovered (or seeded) set of action hashes for a single Vercel deploy. */
+interface ActionSnapshot {
+  /** Vercel deployment id these hashes belong to (from `x-deployment-id`). */
+  deploymentId: string;
+  /** function name → hash. */
+  hashes: ActionHashes;
+  /** Epoch ms when this snapshot was produced. */
+  discoveredAt: number;
+}
+/**
+ * Pluggable persistence for the action snapshot.
+ *
+ * @remarks
+ * The default is in-memory (per-process). In a Lambda/serverless deployment,
+ * supply your own implementation backed by S3/DynamoDB/Redis/`/tmp` so discovery
+ * runs once and is shared across warm invocations and instances.
+ */
+interface ActionCache {
+  load(): Promise<ActionSnapshot | null>;
+  save(snapshot: ActionSnapshot): Promise<void>;
+}
+type AspectRatio = 'portrait' | 'landscape' | 'square';
+type Resolution = '1K' | '2K' | '4K';
+/** `unlimited` = Pro Plus/Max, `play` = free tier, `gems` = gem-based. */
+type GenerationMode = 'unlimited' | 'play' | 'gems';
+/** Job lifecycle status returned by `getHistoryById`. */
+type JobStatus = 'running' | 'success' | 'error';
+/** A trained character referenced inside a generation prompt. */
+interface CharacterRef {
+  id: string;
+  name: string;
+  username: string;
+  image_url: string;
+  /** Optional; serialized as the `$undefined` sentinel when absent. */
+  audio_url?: string;
+}
+/** The `architectureConfig` payload sent to `runArchitecture`. */
+interface ArchitectureConfig {
+  seed: number | null;
+  prompt: string;
+  model_id: string;
+  fast_mode: boolean;
+  resolution: string;
+  architecture: string;
+  aspect_ratio?: AspectRatio;
+  /** Reference image URL, or the `$undefined` sentinel. */
+  image: string;
+  additional_images: string[];
+  characters: CharacterRef[];
+  references: unknown[];
+  audio_references: unknown[];
+  /** Moodboard id, or the `$undefined` sentinel. */
+  moodboard?: string;
+}
+/** The `result` object of a completed generation. */
+interface GenerationResult {
+  data: {
+    image?: string;
+    video?: string;
+    seed?: number;
+    width?: number;
+    height?: number;
+    moderation?: {
+      is_nsfw: boolean;
+      is_forbidden: boolean;
+    };
+  };
+  type?: string;
+  duration?: number;
+}
+/** A single history/generation record returned by the API. */
+interface HistoryItem {
+  id: string;
+  uid?: string;
+  status: JobStatus;
+  created_at?: string;
+  updated_at?: string;
+  error?: unknown;
+  result: GenerationResult | null;
+  concept_id?: string;
+  architecture_config?: ArchitectureConfig;
+  architecture?: string;
+  model_id?: string;
+  membership_tier?: string;
+  [key: string]: unknown;
+}
+/** A page of history records from `getHistoryPaginated`. */
+interface HistoryPage {
+  histories: HistoryItem[];
+  hasMore: boolean;
+}
+interface MageSpaceClientOptions {
+  /** Firebase refresh token extracted from a logged-in browser session. */
+  refreshToken: string;
+  /** Persistence for discovered action hashes (default: in-memory). */
+  cache?: ActionCache;
+  /** Custom `fetch` implementation (default: global `fetch`). */
+  fetch?: FetchLike;
+  /** Override the default browser-like `user-agent`. */
+  userAgent?: string;
+  /** Override the bundled action-hash seed snapshot. */
+  seed?: ActionSnapshot;
+  /** Base URL (default `https://www.mage.space`). */
+  baseUrl?: string;
+  /** Override the Firebase Web API key. */
+  firebaseApiKey?: string;
+}
+interface GenerateOptions {
+  /** Prompt text; supports `@character-username` mentions. */
+  prompt: string;
+  /** Model/concept id. Defaults to the bundled mango-v3-pro concept id. */
+  conceptId?: string;
+  /** Model id (default `mango-v3-pro`). */
+  model?: string;
+  /** Architecture name (default `mango`). */
+  architecture?: string;
+  aspectRatio?: AspectRatio;
+  resolution?: Resolution;
+  /** Random seed (null = random). */
+  seed?: number | null;
+  /** Fast mode (may cost gems). */
+  fastMode?: boolean;
+  /** Characters to inject into the generation. */
+  characters?: CharacterRef[];
+  /**
+   * Reference assets to influence style/composition. Same object shape as
+   * characters; unlike characters they are NOT `@username`-mentioned in the
+   * prompt (see `docs/api/generation.md`).
+   */
+  references?: CharacterRef[];
+  /** First reference image URL. */
+  image?: string;
+  /** Additional reference image URLs. */
+  additionalImages?: string[];
+  /** Override the generation mode (default `unlimited`). */
+  generationMode?: GenerationMode;
+}
+/** Aspect ratios accepted by video architectures (`berry_aspect_ratio`). */
+type VideoAspectRatio = '16:9' | '9:16' | '1:1' | '4:3' | '3:4';
+/** Video output resolutions (`480p` unlimited on Pro Plus; `720p` costs gems). */
+type VideoResolution = '480p' | '720p';
+/**
+ * The `architectureConfig` payload for video architectures.
+ *
+ * @remarks
+ * Differs from the image {@link ArchitectureConfig}: `duration` is a string,
+ * aspect ratio is `berry_aspect_ratio`, and there is no `moodboard` field.
+ */
+interface VideoArchitectureConfig {
+  seed: number | null;
+  prompt: string;
+  model_id: string;
+  fast_mode: boolean;
+  /** `480p` or `720p`. */
+  resolution: string;
+  architecture: string;
+  berry_aspect_ratio?: VideoAspectRatio;
+  /** Clip length in seconds — a string (e.g. `"3"`, `"5"`, `"7"`). */
+  duration: string;
+  /** First-frame image URL, or the `$undefined` sentinel. */
+  image: string;
+  additional_images: string[];
+  characters: CharacterRef[];
+  references: unknown[];
+  audio_references: unknown[];
+}
+interface GenerateVideoOptions {
+  /** Prompt text; supports `@character-username` mentions. */
+  prompt: string;
+  /** Model/concept id. Defaults to the bundled berry-2 concept id. */
+  conceptId?: string;
+  /** Model id (default `berry-2`). */
+  model?: string;
+  /** Architecture name (default `berry`). */
+  architecture?: string;
+  /** Video aspect ratio (default `9:16`). */
+  aspectRatio?: VideoAspectRatio;
+  /** Output resolution (default `480p`). */
+  resolution?: VideoResolution;
+  /** Clip length in seconds as a string (default `"3"`). */
+  duration?: string;
+  /** Random seed (null = random). */
+  seed?: number | null;
+  /** Fast mode (may cost gems). */
+  fastMode?: boolean;
+  /** Characters to inject into the video. */
+  characters?: CharacterRef[];
+  /** Reference assets (same shape as characters; not `@`-mentioned). */
+  references?: CharacterRef[];
+  /** First-frame image URL (text-to-video when omitted). */
+  image?: string;
+  /** Additional reference image URLs. */
+  additionalImages?: string[];
+  /** Override the generation mode (default `unlimited`). */
+  generationMode?: GenerationMode;
+}
+/**
+ * Required confirmation for irreversible, destructive operations.
+ *
+ * @remarks
+ * A safety flag so a mass/permanent delete cannot fire by accident. Pass
+ * `{ confirm: true }` to actually execute.
+ */
+interface ConfirmOptions {
+  confirm: boolean;
+}
+interface WaitOptions {
+  /** Poll interval in ms (default 4000). */
+  intervalMs?: number;
+  /** Overall timeout in ms (default 300000). */
+  timeoutMs?: number;
+  /** Abort signal to cancel waiting. */
+  signal?: AbortSignal;
+}
+interface ListHistoryOptions {
+  /** Max results (default 10). */
+  limit?: number;
+  /** Pagination offset (default 0). */
+  offset?: number;
+  /** Filter by status; `all` disables the status filter (default `success`). */
+  status?: JobStatus | 'all';
+}
+/** Whether an asset is driven by an image or an audio reference. */
+type Modality = 'image' | 'audio';
+/** Asset visibility. */
+type Visibility = 'private' | 'public';
+/**
+ * A trained character (or reference asset) as returned by the API.
+ *
+ * @remarks
+ * References share this shape with `variant: "reference"`; characters use
+ * `variant: "character"`.
+ */
+interface Character {
+  id: string;
+  uid?: string;
+  name: string;
+  username: string;
+  image_url: string;
+  audio_url: string | null;
+  modality?: Modality;
+  description?: string | null;
+  tags?: string[];
+  visibility?: Visibility;
+  moderation?: string[];
+  num_plays_all_time?: number;
+  num_plays_monthly?: number;
+  num_plays_daily?: number;
+  created_at?: string;
+  is_deleted?: boolean;
+  is_featured?: boolean;
+  variant?: string;
+  [key: string]: unknown;
+}
+/** A reference asset — structurally identical to {@link Character}. */
+type Reference = Character;
+/** Parsed result of `getMentionSuggestionsParallel`. */
+interface CharacterSearchResult {
+  characters: Character[];
+  references: Reference[];
+  moodboards: unknown[];
+}
+interface SearchCharactersOptions {
+  /** Search text (matches character name). */
+  query: string;
+  /** Max results (default 10). */
+  limit?: number;
+  /** Include public references in the results (default false). */
+  includePublicReferences?: boolean;
+  /** Reference modalities to include (default `['image', 'audio']`). */
+  referenceModalities?: Modality[];
+}
+interface CreateCharacterInput {
+  /** Display name. */
+  name: string;
+  /** Unique @-mention handle (name + short suffix). */
+  username: string;
+  /** CDN URL from {@link uploadCharacterImage} or an existing character. */
+  image_url: string;
+  /** Voice audio URL (default null). */
+  audio_url?: string | null;
+  /** Optional description (default null). */
+  description?: string | null;
+  /** Category tags (default `[]`). */
+  tags?: string[];
+  /** Visibility (default `private`). */
+  visibility?: Visibility;
+  /** Moderation flags — always `[]` for new characters. */
+  moderation?: string[];
+}
+interface UpdateCharacterInput {
+  name?: string;
+  description?: string | null;
+  tags?: string[];
+  visibility?: Visibility;
+  audio_url?: string | null;
+}
+interface CreateReferenceInput {
+  /** Display name. */
+  name: string;
+  /** Unique handle (name + short suffix). */
+  username: string;
+  /** CDN URL from {@link uploadReferenceImage} (required for image refs). */
+  image_url?: string;
+  /** Audio URL (required for audio refs). */
+  audio_url?: string | null;
+  /** Reference modality (default `image`). */
+  modality?: Modality;
+  /** `reference` for image refs, `audio` for audio refs (default `reference`). */
+  variant?: string;
+  description?: string | null;
+  tags?: string[];
+  visibility?: Visibility;
+  moderation?: string[];
+}
+/** Reference asset variants. */
+type ReferenceVariant = 'reference' | 'object' | 'outfit' | 'pose';
+interface UpdateReferenceInput {
+  name?: string;
+  description?: string | null;
+  tags?: string[];
+  visibility?: Visibility;
+}
+/** Ordering for the paginated reference feed. */
+type ReferenceOrder = 'trending' | 'top' | 'newest' | 'oldest';
+interface ListReferencesOptions {
+  /** Max results per page (default 20). */
+  limit?: number;
+  /** Pagination offset (default 0). */
+  offset?: number;
+  /** Filter by owner uid (omit for the public feed). */
+  uid?: string;
+  /** Filter by visibility. */
+  visibility?: Visibility;
+  /** Sort order (default `top`). */
+  orderBy?: ReferenceOrder;
+  /** Only featured references. */
+  featuredOnly?: boolean;
+  /** Filter by modality (default `image`). */
+  modality?: Modality;
+}
+/** A page of references from `getReferencesPaginated`. */
+interface ReferencePage {
+  references: Reference[];
+  hasMore: boolean;
+}
+interface ListCharactersOptions {
+  /** Max results per page (default 100). */
+  limit?: number;
+  /** Pagination offset (default 0). */
+  offset?: number;
+  /** Filter by owner uid (omit for the public feed). */
+  uid?: string;
+  /** Filter by visibility. */
+  visibility?: Visibility;
+  /** Filter by modality. */
+  modality?: Modality;
+  /** Only featured characters. */
+  featured?: boolean;
+}
+/** A page of characters from `getCharactersPaginated`. */
+interface CharacterPage {
+  characters: Character[];
+  hasMore: boolean;
+}
+/** A permanently saved creation (as opposed to transient history). */
+interface Creation {
+  id: string;
+  uid?: string;
+  /** Permanent CDN URL (not `/temp/30d/`). */
+  url: string;
+  hash?: string;
+  type?: 'image' | 'video';
+  visibility?: Visibility;
+  concept_id?: string;
+  architecture_config?: ArchitectureConfig;
+  metadata?: {
+    seed?: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    moderation?: {
+      is_nsfw: boolean;
+      is_forbidden: boolean;
+    };
+  };
+  created_at?: string;
+  updated_at?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+/** A page of creations from `getCreationsPaginatedParallel`. */
+interface CreationPage {
+  creations: Creation[];
+  hasMore: boolean;
+}
+interface ListCreationsOptions {
+  /** Max results (default 10). */
+  limit?: number;
+  /** Pagination offset (default 0). */
+  offset?: number;
+}
+interface GenerateVoiceOptions {
+  /** CDN URL of the character's reference image. */
+  imageUrl: string;
+  /** Text describing the desired voice (default empty). */
+  guidancePrompt?: string;
+}
+/** Result of `generateCharacterVoice`. */
+interface VoiceResult {
+  ok: boolean;
+  data?: {
+    /** CDN URL of the generated MP3 voice. */
+    audioUrl: string;
+    /** Gems charged for the generation. */
+    gemsCharged?: number;
+  };
+  error?: {
+    code: string;
+    required_gems?: number;
+    balance_gems?: number;
+  };
+}
+//#endregion
+//#region lib/actions.d.ts
+/** Default in-process snapshot cache. */
+declare class InMemoryActionCache implements ActionCache {
+  private snapshot;
+  load(): Promise<ActionSnapshot | null>;
+  save(snapshot: ActionSnapshot): Promise<void>;
+}
+interface DiscoveryOptions {
+  fetch: FetchLike;
+  baseUrl: string;
+  /** Single page to scrape for chunk references (overrides {@link discoveryPaths}). */
+  discoveryPath?: string;
+  /** Pages to scrape and union (default: the main app routes). */
+  discoveryPaths?: string[];
+}
+/**
+ * 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.
+ */
+declare function discoverActions(opts: DiscoveryOptions): Promise<ActionSnapshot>;
+interface ActionRegistryOptions {
+  fetch: FetchLike;
+  baseUrl: string;
+  cache?: ActionCache;
+  seed?: ActionSnapshot;
+  discoveryPath?: string;
+  discoveryPaths?: string[];
+  /** Re-discover when the snapshot is older than this (ms). 0 = never by age. */
+  maxAgeMs?: number;
+}
+/**
+ * Serves action hashes from a warm seed / pluggable cache, discovering lazily and
+ * refreshing on staleness. Concurrent refreshes are de-duplicated (single-flight).
+ */
+declare class ActionRegistry {
+  private readonly fetch;
+  private readonly baseUrl;
+  private readonly cache;
+  private readonly seed;
+  private readonly discoveryPath;
+  private readonly discoveryPaths;
+  private readonly maxAgeMs;
+  private snapshot;
+  private inflight;
+  constructor(opts: ActionRegistryOptions);
+  private isStale;
+  /** Return the current snapshot, loading from cache/seed or discovering as needed. */
+  getSnapshot(): Promise<ActionSnapshot>;
+  /** Force re-discovery. Concurrent callers share one in-flight discovery. */
+  refresh(): Promise<ActionSnapshot>;
+  /** Resolve a function name to its current hash + deployment id. */
+  getHash(action: ActionName | string): Promise<{
+    hash: string;
+    deploymentId: string;
+  }>;
+  /** Drop the cached snapshot and re-discover (called on a stale 404). */
+  invalidate(): Promise<ActionSnapshot>;
+}
+//#endregion
+//#region lib/http.d.ts
+interface CallActionParams {
+  /** Server Action function name (resolved to a hash via the registry). */
+  action: string;
+  /** Page path to POST to (e.g. `/explore`, `/creations`). */
+  path: string;
+  /** Request body — always a JSON array of arguments. */
+  args: unknown[];
+  /** `__session` cookie value for authenticated actions. */
+  session?: string;
+}
+interface CallActionResult<T> {
+  data: T;
+  headers: Headers;
+  deploymentId: string;
+}
+declare class HttpClient {
+  private readonly registry;
+  private readonly fetchImpl;
+  private readonly baseUrl;
+  private readonly userAgent;
+  constructor(registry: ActionRegistry, fetchImpl: FetchLike, baseUrl: string, userAgent?: string);
+  callAction<T = unknown>(params: CallActionParams, retried?: boolean): Promise<CallActionResult<T>>;
+}
+//#endregion
+//#region lib/auth.d.ts
+interface AuthManagerOptions {
+  refreshToken: string;
+  http: HttpClient;
+  fetch: FetchLike;
+  firebaseApiKey?: string;
+  /** Page path for the `createUserSession` action (default `/creations`). */
+  sessionPath?: string;
+}
+declare class AuthManager {
+  private refreshToken;
+  private readonly http;
+  private readonly fetchImpl;
+  private readonly apiKey;
+  private readonly sessionPath;
+  private tokens;
+  private session;
+  constructor(opts: AuthManagerOptions);
+  /** Return a valid Firebase ID token, refreshing via the refresh token if needed. */
+  getIdToken(): Promise<string>;
+  /** Return the Firebase uid (fetching an ID token first if necessary). */
+  getUserId(): Promise<string>;
+  /** Return a valid `__session` cookie, creating one via `createUserSession` if needed. */
+  getSession(): Promise<string>;
+  private refreshTokens;
+}
+//#endregion
+//#region lib/characters.d.ts
+declare class CharactersService {
+  private readonly http;
+  private readonly auth;
+  constructor(http: HttpClient, auth: AuthManager);
+  /** Search the caller's characters (and optionally public references) by name. */
+  search(opts: SearchCharactersOptions): Promise<CharacterSearchResult>;
+  /** Create a new character from an already-uploaded image URL. */
+  create(input: CreateCharacterInput): Promise<Character>;
+  /** Update a character's mutable fields (name, description, tags, visibility, voice). */
+  update(id: string, patch: UpdateCharacterInput): Promise<Character>;
+  /** Soft-delete a character. */
+  delete(id: string): Promise<void>;
+  /** Fetch a single character by id; resolves to `null` when it does not exist. */
+  get(id: string): Promise<Character | null>;
+  /** Fetch multiple characters by id in a single call. */
+  getMany(ids: string[]): Promise<Character[]>;
+  /** Make a character public. */
+  publish(id: string): Promise<void>;
+  /** Make a character private. */
+  unpublish(id: string): Promise<void>;
+  /**
+   * Upload a character reference image (base64 data URL) and return its CDN URL.
+   *
+   * @param dataUrl - `data:image/jpeg;base64,...` (JPEG preferred; PNG/WebP ok).
+   */
+  uploadImage(dataUrl: string): Promise<string>;
+  /**
+   * Browse characters with pagination.
+   *
+   * @remarks
+   * Omit `uid` to browse the public/featured feed; pass it to page through a
+   * single user's characters.
+   */
+  listPaginated(opts?: ListCharactersOptions): Promise<CharacterPage>;
+  /**
+   * 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.
+   */
+  generateVoice(opts: GenerateVoiceOptions): Promise<VoiceResult>;
+  /**
+   * Follow a (public) character.
+   *
+   * @experimental Request body inferred from JS bundle; not yet verified live.
+   */
+  follow(id: string): Promise<void>;
+  /**
+   * Unfollow a character.
+   *
+   * @experimental Request body inferred from JS bundle; not yet verified live.
+   */
+  unfollow(id: string): Promise<void>;
+}
+//#endregion
+//#region lib/references.d.ts
+declare class ReferencesService {
+  private readonly http;
+  private readonly auth;
+  constructor(http: HttpClient, auth: AuthManager);
+  /**
+   * Upload a reference image (base64 data URL) and return its CDN URL.
+   *
+   * @param dataUrl - `data:image/jpeg;base64,...` (JPEG preferred; PNG/WebP ok).
+   */
+  uploadImage(dataUrl: string): Promise<string>;
+  /** Create a reusable reference from an uploaded image/audio URL. */
+  create(input: CreateReferenceInput): Promise<Reference>;
+  /** Update a reference's mutable fields (name, description, tags, visibility). */
+  update(id: string, patch: UpdateReferenceInput): Promise<Reference>;
+  /**
+   * Permanently delete a reference (soft-delete). Irreversible — requires
+   * `{ confirm: true }`.
+   */
+  delete(id: string, opts?: ConfirmOptions): Promise<void>;
+  /** List the caller's own references for a given modality (default `image`). */
+  list(modality?: Modality): Promise<Reference[]>;
+  /**
+   * Browse references with pagination.
+   *
+   * @remarks
+   * Omit `uid` to browse the public/featured feed; pass it to page through a
+   * single user's references.
+   */
+  listPaginated(opts?: ListReferencesOptions): Promise<ReferencePage>;
+}
+//#endregion
+//#region lib/client.d.ts
+declare class MageSpaceClient {
+  private readonly registry;
+  private readonly auth;
+  private readonly generationService;
+  private readonly historyService;
+  /** Character management (search, CRUD, pagination, uploads). */
+  readonly characters: CharactersService;
+  /** Reference asset management (upload, create, update, list, feed). */
+  readonly references: ReferencesService;
+  constructor(options: MageSpaceClientOptions);
+  /** Submit a generation job; returns its `historyId`. */
+  generate(options: GenerateOptions): Promise<{
+    historyId: string;
+  }>;
+  /** Submit a video generation job (Berry-2 family); returns its `historyId`. */
+  generateVideo(options: GenerateVideoOptions): Promise<{
+    historyId: string;
+  }>;
+  /** Fetch the current state of a generation by id. */
+  getResult(historyId: string): Promise<HistoryItem>;
+  /** Poll until a generation finishes (or fails / times out). */
+  waitForResult(historyId: string, options?: WaitOptions): Promise<HistoryItem>;
+  /** Cancel a running generation job. */
+  cancelJob(historyId: string): Promise<void>;
+  /** List past generations for the authenticated user. */
+  listHistory(options?: ListHistoryOptions): Promise<HistoryPage>;
+  /** List the user's permanently saved creations. */
+  listCreations(options?: ListCreationsOptions): Promise<CreationPage>;
+  /** Save a completed generation result as a permanent creation. */
+  saveCreation(result: GenerationResult): Promise<void>;
+  /** Permanently delete a history item. Irreversible — requires `{ confirm: true }`. */
+  deleteHistory(historyId: string, options?: ConfirmOptions): Promise<void>;
+  /** Permanently delete many history items. Irreversible — requires `{ confirm: true }`. */
+  deleteManyHistories(historyIds: string[], options?: ConfirmOptions): Promise<void>;
+  /** Permanently delete a saved creation. Irreversible — requires `{ confirm: true }`. */
+  deleteCreation(creationId: string, options?: ConfirmOptions): Promise<void>;
+  /** Permanently delete many creations. Irreversible — requires `{ confirm: true }`. */
+  deleteManyCreations(creationIds: string[], options?: ConfirmOptions): Promise<void>;
+  /** Force re-discovery of the Server Action hashes. */
+  refreshActions(): Promise<ActionSnapshot>;
+}
+//#endregion
+//#region lib/errors.d.ts
+/** Typed error hierarchy for the mage.space client. */
+/** Base class for every error thrown by this library. */
+declare class MageSpaceError extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** Authentication failures (token refresh, session creation). */
+declare class AuthError extends MageSpaceError {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** Action-hash discovery failures (page/chunk fetch, empty registry). */
+declare class DiscoveryError extends MageSpaceError {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** A Server Action returned 404, indicating a stale (post-deploy) hash. */
+declare class StaleActionError extends MageSpaceError {
+  readonly action: string;
+  constructor(action: string, options?: {
+    cause?: unknown;
+  });
+}
+/** Failures while submitting or polling a generation job. */
+declare class GenerationError extends MageSpaceError {
+  readonly code?: number | undefined;
+  constructor(message: string, code?: number | undefined, options?: {
+    cause?: unknown;
+  });
+}
+/** Failure to parse a React Server Component (RSC) wire response. */
+declare class RscParseError extends MageSpaceError {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+/** A wait/poll operation exceeded its deadline or was aborted. */
+declare class TimeoutError extends MageSpaceError {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region lib/rsc.d.ts
+/**
+ * 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.
+ */
+declare function parseFlightRows(text: string): Map<string, unknown>;
+/** Recursively resolve Flight sentinels/references within a parsed value. */
+declare function resolveFlightValue(value: unknown, rows: Map<string, unknown>, seen?: Set<string>): unknown;
+/**
+ * Parse a Server Action response and return the action's resolved return value.
+ *
+ * @throws {RscParseError} when the response contains no parseable rows.
+ */
+declare function parseServerActionResponse<T = unknown>(text: string): T;
+/**
+ * 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`).
+ */
+declare function unwrapResult<T>(value: unknown): T;
+//#endregion
+//#region lib/seed.d.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).
+ */
+declare const SEED_SNAPSHOT: ActionSnapshot;
+//#endregion
+//#region lib/index.d.ts
+/** Public entry point for `@zweer/mage-space-client`. */
+declare const VERSION = "0.0.0";
+//#endregion
+export { type ActionCache, type ActionHashes, type ActionName, ActionRegistry, type ActionSnapshot, type ArchitectureConfig, type AspectRatio, AuthError, type AuthTokens, type Character, type CharacterPage, type CharacterRef, type CharacterSearchResult, CharactersService, type ConfirmOptions, type CreateCharacterInput, type CreateReferenceInput, type Creation, type CreationPage, DiscoveryError, type FetchLike, type GenerateOptions, type GenerateVideoOptions, type GenerateVoiceOptions, GenerationError, type GenerationMode, type GenerationResult, type HistoryItem, type HistoryPage, InMemoryActionCache, type JobStatus, type ListCharactersOptions, type ListCreationsOptions, type ListHistoryOptions, type ListReferencesOptions, MageSpaceClient, type MageSpaceClientOptions, MageSpaceError, type Modality, type Reference, type ReferenceOrder, type ReferencePage, type ReferenceVariant, ReferencesService, type Resolution, RscParseError, SEED_SNAPSHOT, type SearchCharactersOptions, type SessionState, StaleActionError, TimeoutError, type UpdateCharacterInput, type UpdateReferenceInput, VERSION, type VideoArchitectureConfig, type VideoAspectRatio, type VideoResolution, type Visibility, type VoiceResult, type WaitOptions, discoverActions, parseFlightRows, parseServerActionResponse, resolveFlightValue, unwrapResult };
+//# sourceMappingURL=index.d.cts.map