@zweer/mage-space-client 1.1.2 → 1.3.0

package/dist/index.d.cts

@@ -1,11 +1,56 @@
-//#region lib/types.d.ts
+//#region lib/targets.d.ts
+/**
+ * Per-host {@link Target} descriptors.
+ *
+ * mage.space is migrating from production (`https://www.mage.space`) to a new
+ * portal (`https://beta.mage.space`). Rather than hard-coding one base URL and
+ * one action-name set, each host is modelled as a `Target` so host differences
+ * (renamed actions, poll strategy) live in a single table. The client holds an
+ * ordered chain `[production, beta]` and advances to the next target only when
+ * the active host can no longer serve a required action.
+ */
+/** Hosts the client can talk to. */
+type TargetKey = 'production' | 'beta';
+/** How a single history-status read is performed on a given host. */
+type PollStrategy = 'byId' | 'paginated';
+/**
+ * Logical operations the generation/history services invoke, decoupled from the
+ * host-specific wire names. `createUserSession` is intentionally NOT a member:
+ * it is resolved by its literal name on both hosts (see `lib/auth.ts`).
+ */
+type LogicalAction = 'submitGeneration' | 'getHistoryById' | 'cancelJob' | 'listHistory' | 'listCreations';
+/** A single host the client can target. */
+interface Target {
+  readonly key: TargetKey;
+  readonly baseUrl: string;
+  /** logical name → host-specific wire name; unlisted names resolve to themselves. */
+  readonly actionNames: Readonly<Partial<Record<LogicalAction, string>>>;
+  readonly pollStrategy: PollStrategy;
+}
+/** Resolve a logical action to its host-specific wire name (identity if unlisted). */
+declare function resolveActionName(target: Target, logical: LogicalAction): string;
 /**
- * Shared type definitions for the mage.space client.
+ * Production target.
  *
  * @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`.
+ * Maps each logical action to the wire name the current production deploy
+ * actually serves (all VERIFIED against `lib/seed.ts` / the existing MSW tests):
+ * `submitGeneration → runArchitecture`, `cancelJob → cancelArchitectureJob`,
+ * `listHistory → getHistoryPaginated`, `listCreations → getCreationsPaginatedParallel`,
+ * and `getHistoryById → getHistoryById` (identity). The table is explicit rather
+ * than empty so production behaviour is reproduced exactly regardless of the
+ * logical-name vocabulary.
  */
+declare const PRODUCTION_TARGET: Target;
+/**
+ * Beta target. Beta facts are assumptions pending a reverse-engineering capture
+ * under `docs/api/beta` — treat them as unverified until that doc lands.
+ */
+declare const BETA_TARGET: Target;
+/** Default ordered fallback chain: production first, then beta. */
+declare const DEFAULT_TARGET_CHAIN: readonly Target[];
+//#endregion
+//#region lib/types.d.ts
 /** 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. */
@@ -27,7 +72,7 @@ interface SessionState {
   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';
+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' | 'getCreationsPaginated' | '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. */
@@ -136,6 +181,21 @@ interface MageSpaceClientOptions {
   baseUrl?: string;
   /** Override the Firebase Web API key. */
   firebaseApiKey?: string;
+  /**
+   * Host-fallback behaviour. Default: production first, with an automatic,
+   * sticky fallback to beta when production can no longer serve a required
+   * action. Cannot be combined with `baseUrl` (which pins a single host).
+   */
+  fallback?: FallbackOptions;
+}
+/** Configuration for the automatic beta-portal fallback. */
+interface FallbackOptions {
+  /** Host to start on. Default `'production'`. `'beta'` forces beta from the first call. */
+  start?: TargetKey;
+  /** Auto-advance to the next target on a definitive action-unavailable signal. Default `true`. */
+  auto?: boolean;
+  /** Override the ordered target chain. Advanced/testing. Default `DEFAULT_TARGET_CHAIN`. */
+  chain?: readonly Target[];
 }
 interface GenerateOptions {
   /** Prompt text; supports `@character-username` mentions. */
@@ -305,8 +365,15 @@ interface SearchCharactersOptions {
 interface CreateCharacterInput {
   /** Display name. */
   name: string;
-  /** Unique @-mention handle (name + short suffix). */
-  username: string;
+  /**
+   * Unique @-mention handle. Max 15 chars, lowercase `a-z`, `0-9`, `_`, `-`,
+   * must start with a letter.
+   *
+   * @remarks
+   * When omitted, one is auto-generated from `name` with a 4-char random suffix
+   * (matching the web UI behavior), truncated to 15 chars.
+   */
+  username?: string;
   /** CDN URL from {@link uploadCharacterImage} or an existing character. */
   image_url: string;
   /** Voice audio URL (default null). */
@@ -330,8 +397,11 @@ interface UpdateCharacterInput {
 interface CreateReferenceInput {
   /** Display name. */
   name: string;
-  /** Unique handle (name + short suffix). */
-  username: string;
+  /**
+   * Unique handle. Max 15 chars, lowercase `a-z`, `0-9`, `_`, `-`, starts with a letter.
+   * When omitted, auto-generated from `name` with a 4-char random suffix.
+   */
+  username?: string;
   /** CDN URL from {@link uploadReferenceImage} (required for image refs). */
   image_url?: string;
   /** Audio URL (required for audio refs). */
@@ -535,15 +605,23 @@ declare class HttpClient {
   private readonly registry;
   private readonly fetchImpl;
   private readonly baseUrl;
+  private readonly targetKey;
   private readonly userAgent;
-  constructor(registry: ActionRegistry, fetchImpl: FetchLike, baseUrl: string, userAgent?: string);
+  constructor(registry: ActionRegistry, fetchImpl: FetchLike, baseUrl: string, targetKey: string, userAgent?: string);
+  /** A response that means the action is unavailable (stale hash or gone). */
+  private isUnavailable;
   callAction<T = unknown>(params: CallActionParams, retried?: boolean): Promise<CallActionResult<T>>;
 }
 //#endregion
 //#region lib/auth.d.ts
 interface AuthManagerOptions {
   refreshToken: string;
-  http: HttpClient;
+  /**
+   * Accessor for the active host's {@link HttpClient}. A closure (not the client
+   * itself) so `createUserSession` always hits whichever host is currently
+   * active after an automatic fallback.
+   */
+  getHttp: () => HttpClient;
   fetch: FetchLike;
   firebaseApiKey?: string;
   /** Page path for the `createUserSession` action (default `/creations`). */
@@ -551,13 +629,19 @@ interface AuthManagerOptions {
 }
 declare class AuthManager {
   private refreshToken;
-  private readonly http;
+  private readonly getHttp;
   private readonly fetchImpl;
   private readonly apiKey;
   private readonly sessionPath;
   private tokens;
   private session;
   constructor(opts: AuthManagerOptions);
+  /**
+   * Drop the cached `__session` cookie so the next {@link getSession} mints a
+   * fresh one against the (newly) active host. The Firebase token chain is kept
+   * because it is host-independent.
+   */
+  resetSession(): void;
   /** 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). */
@@ -657,15 +741,43 @@ declare class ReferencesService {
 //#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). */
+  private readonly chain;
+  private readonly auto;
+  private readonly contextDeps;
+  private readonly contexts;
+  private activeIndex;
+  private activeContext;
+  private activeBundle;
+  /**
+   * Character management (search, CRUD, pagination, uploads).
+   *
+   * @remarks
+   * Bound to the initial host (production by default) and does not follow an
+   * automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+   * to use these against beta.
+   */
   readonly characters: CharactersService;
-  /** Reference asset management (upload, create, update, list, feed). */
+  /**
+   * Reference asset management (upload, create, update, list, feed).
+   *
+   * @remarks
+   * Bound to the initial host (production by default) and does not follow an
+   * automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+   * to use these against beta.
+   */
   readonly references: ReferencesService;
   constructor(options: MageSpaceClientOptions);
+  /** Lazily build (and memoise) the {@link TargetContext} for a chain index. */
+  private getContext;
+  /** Build the generation/history service bundle for a context. */
+  private buildBundle;
+  /** Advance to the next target (sticky). Returns `null` if none or `auto` is off. */
+  private advanceTarget;
+  /** Whether an error is a definitive action-unavailable signal (a fallback trigger). */
+  private shouldFallback;
+  /** Run `op` against the active bundle, switching to the next target once on a trigger. */
+  private withFallback;
   /** Submit a generation job; returns its `historyId`. */
   generate(options: GenerateOptions): Promise<{
     historyId: string;
@@ -694,10 +806,12 @@ declare class MageSpaceClient {
   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. */
+  /** Force re-discovery of the Server Action hashes on the active host. */
   refreshActions(): Promise<ActionSnapshot>;
   /** Return the authenticated user's Firebase uid. */
   getUid(): Promise<string>;
+  /** Return the key of the currently active target (`'production'` or `'beta'`). */
+  getActiveTarget(): TargetKey;
 }
 //#endregion
 //#region lib/errors.d.ts
@@ -716,11 +830,34 @@ declare class AuthError extends MageSpaceError {
 }
 /** Action-hash discovery failures (page/chunk fetch, empty registry). */
 declare class DiscoveryError extends MageSpaceError {
+  /**
+   * `true` when the action name was absent even after a forced re-discovery
+   * (a fallback trigger); `false` for scrape failures (no chunks/no hashes).
+   */
+  readonly notFound: boolean;
   constructor(message: string, options?: {
     cause?: unknown;
+    notFound?: boolean;
   });
 }
-/** A Server Action returned 404, indicating a stale (post-deploy) hash. */
+/**
+ * A required action is unavailable on the active host (a persistent 404 / HTML
+ * fallback that survived one in-place re-discovery). A fallback trigger.
+ */
+declare class ActionUnavailableError extends MageSpaceError {
+  readonly action: string;
+  readonly targetKey: string;
+  constructor(action: string, targetKey: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * A Server Action returned 404, indicating a stale (post-deploy) hash.
+ *
+ * @deprecated Legacy export kept for backward compatibility; no longer thrown.
+ * The current signal for a definitively unavailable action is
+ * {@link ActionUnavailableError}.
+ */
 declare class StaleActionError extends MageSpaceError {
   readonly action: string;
   constructor(action: string, options?: {
@@ -798,5 +935,5 @@ declare const SEED_SNAPSHOT: ActionSnapshot;
 /** 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 };
+export { type ActionCache, type ActionHashes, type ActionName, ActionRegistry, type ActionSnapshot, ActionUnavailableError, type ArchitectureConfig, type AspectRatio, AuthError, type AuthTokens, BETA_TARGET, type Character, type CharacterPage, type CharacterRef, type CharacterSearchResult, CharactersService, type ConfirmOptions, type CreateCharacterInput, type CreateReferenceInput, type Creation, type CreationPage, DEFAULT_TARGET_CHAIN, DiscoveryError, type FallbackOptions, 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, type LogicalAction, MageSpaceClient, type MageSpaceClientOptions, MageSpaceError, type Modality, PRODUCTION_TARGET, type PollStrategy, type Reference, type ReferenceOrder, type ReferencePage, type ReferenceVariant, ReferencesService, type Resolution, RscParseError, SEED_SNAPSHOT, type SearchCharactersOptions, type SessionState, StaleActionError, type Target, type TargetKey, TimeoutError, type UpdateCharacterInput, type UpdateReferenceInput, VERSION, type VideoArchitectureConfig, type VideoAspectRatio, type VideoResolution, type Visibility, type VoiceResult, type WaitOptions, discoverActions, parseFlightRows, parseServerActionResponse, resolveActionName, resolveFlightValue, unwrapResult };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../lib/types.ts","../lib/actions.ts","../lib/http.ts","../lib/auth.ts","../lib/characters.ts","../lib/references.ts","../lib/client.ts","../lib/errors.ts","../lib/rsc.ts","../lib/seed.ts","../lib/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../lib/targets.ts","../lib/types.ts","../lib/actions.ts","../lib/http.ts","../lib/auth.ts","../lib/characters.ts","../lib/references.ts","../lib/client.ts","../lib/errors.ts","../lib/rsc.ts","../lib/seed.ts","../lib/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,11 +1,56 @@
-//#region lib/types.d.ts
+//#region lib/targets.d.ts
+/**
+ * Per-host {@link Target} descriptors.
+ *
+ * mage.space is migrating from production (`https://www.mage.space`) to a new
+ * portal (`https://beta.mage.space`). Rather than hard-coding one base URL and
+ * one action-name set, each host is modelled as a `Target` so host differences
+ * (renamed actions, poll strategy) live in a single table. The client holds an
+ * ordered chain `[production, beta]` and advances to the next target only when
+ * the active host can no longer serve a required action.
+ */
+/** Hosts the client can talk to. */
+type TargetKey = 'production' | 'beta';
+/** How a single history-status read is performed on a given host. */
+type PollStrategy = 'byId' | 'paginated';
+/**
+ * Logical operations the generation/history services invoke, decoupled from the
+ * host-specific wire names. `createUserSession` is intentionally NOT a member:
+ * it is resolved by its literal name on both hosts (see `lib/auth.ts`).
+ */
+type LogicalAction = 'submitGeneration' | 'getHistoryById' | 'cancelJob' | 'listHistory' | 'listCreations';
+/** A single host the client can target. */
+interface Target {
+  readonly key: TargetKey;
+  readonly baseUrl: string;
+  /** logical name → host-specific wire name; unlisted names resolve to themselves. */
+  readonly actionNames: Readonly<Partial<Record<LogicalAction, string>>>;
+  readonly pollStrategy: PollStrategy;
+}
+/** Resolve a logical action to its host-specific wire name (identity if unlisted). */
+declare function resolveActionName(target: Target, logical: LogicalAction): string;
 /**
- * Shared type definitions for the mage.space client.
+ * Production target.
  *
  * @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`.
+ * Maps each logical action to the wire name the current production deploy
+ * actually serves (all VERIFIED against `lib/seed.ts` / the existing MSW tests):
+ * `submitGeneration → runArchitecture`, `cancelJob → cancelArchitectureJob`,
+ * `listHistory → getHistoryPaginated`, `listCreations → getCreationsPaginatedParallel`,
+ * and `getHistoryById → getHistoryById` (identity). The table is explicit rather
+ * than empty so production behaviour is reproduced exactly regardless of the
+ * logical-name vocabulary.
  */
+declare const PRODUCTION_TARGET: Target;
+/**
+ * Beta target. Beta facts are assumptions pending a reverse-engineering capture
+ * under `docs/api/beta` — treat them as unverified until that doc lands.
+ */
+declare const BETA_TARGET: Target;
+/** Default ordered fallback chain: production first, then beta. */
+declare const DEFAULT_TARGET_CHAIN: readonly Target[];
+//#endregion
+//#region lib/types.d.ts
 /** 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. */
@@ -27,7 +72,7 @@ interface SessionState {
   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';
+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' | 'getCreationsPaginated' | '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. */
@@ -136,6 +181,21 @@ interface MageSpaceClientOptions {
   baseUrl?: string;
   /** Override the Firebase Web API key. */
   firebaseApiKey?: string;
+  /**
+   * Host-fallback behaviour. Default: production first, with an automatic,
+   * sticky fallback to beta when production can no longer serve a required
+   * action. Cannot be combined with `baseUrl` (which pins a single host).
+   */
+  fallback?: FallbackOptions;
+}
+/** Configuration for the automatic beta-portal fallback. */
+interface FallbackOptions {
+  /** Host to start on. Default `'production'`. `'beta'` forces beta from the first call. */
+  start?: TargetKey;
+  /** Auto-advance to the next target on a definitive action-unavailable signal. Default `true`. */
+  auto?: boolean;
+  /** Override the ordered target chain. Advanced/testing. Default `DEFAULT_TARGET_CHAIN`. */
+  chain?: readonly Target[];
 }
 interface GenerateOptions {
   /** Prompt text; supports `@character-username` mentions. */
@@ -305,8 +365,15 @@ interface SearchCharactersOptions {
 interface CreateCharacterInput {
   /** Display name. */
   name: string;
-  /** Unique @-mention handle (name + short suffix). */
-  username: string;
+  /**
+   * Unique @-mention handle. Max 15 chars, lowercase `a-z`, `0-9`, `_`, `-`,
+   * must start with a letter.
+   *
+   * @remarks
+   * When omitted, one is auto-generated from `name` with a 4-char random suffix
+   * (matching the web UI behavior), truncated to 15 chars.
+   */
+  username?: string;
   /** CDN URL from {@link uploadCharacterImage} or an existing character. */
   image_url: string;
   /** Voice audio URL (default null). */
@@ -330,8 +397,11 @@ interface UpdateCharacterInput {
 interface CreateReferenceInput {
   /** Display name. */
   name: string;
-  /** Unique handle (name + short suffix). */
-  username: string;
+  /**
+   * Unique handle. Max 15 chars, lowercase `a-z`, `0-9`, `_`, `-`, starts with a letter.
+   * When omitted, auto-generated from `name` with a 4-char random suffix.
+   */
+  username?: string;
   /** CDN URL from {@link uploadReferenceImage} (required for image refs). */
   image_url?: string;
   /** Audio URL (required for audio refs). */
@@ -535,15 +605,23 @@ declare class HttpClient {
   private readonly registry;
   private readonly fetchImpl;
   private readonly baseUrl;
+  private readonly targetKey;
   private readonly userAgent;
-  constructor(registry: ActionRegistry, fetchImpl: FetchLike, baseUrl: string, userAgent?: string);
+  constructor(registry: ActionRegistry, fetchImpl: FetchLike, baseUrl: string, targetKey: string, userAgent?: string);
+  /** A response that means the action is unavailable (stale hash or gone). */
+  private isUnavailable;
   callAction<T = unknown>(params: CallActionParams, retried?: boolean): Promise<CallActionResult<T>>;
 }
 //#endregion
 //#region lib/auth.d.ts
 interface AuthManagerOptions {
   refreshToken: string;
-  http: HttpClient;
+  /**
+   * Accessor for the active host's {@link HttpClient}. A closure (not the client
+   * itself) so `createUserSession` always hits whichever host is currently
+   * active after an automatic fallback.
+   */
+  getHttp: () => HttpClient;
   fetch: FetchLike;
   firebaseApiKey?: string;
   /** Page path for the `createUserSession` action (default `/creations`). */
@@ -551,13 +629,19 @@ interface AuthManagerOptions {
 }
 declare class AuthManager {
   private refreshToken;
-  private readonly http;
+  private readonly getHttp;
   private readonly fetchImpl;
   private readonly apiKey;
   private readonly sessionPath;
   private tokens;
   private session;
   constructor(opts: AuthManagerOptions);
+  /**
+   * Drop the cached `__session` cookie so the next {@link getSession} mints a
+   * fresh one against the (newly) active host. The Firebase token chain is kept
+   * because it is host-independent.
+   */
+  resetSession(): void;
   /** 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). */
@@ -657,15 +741,43 @@ declare class ReferencesService {
 //#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). */
+  private readonly chain;
+  private readonly auto;
+  private readonly contextDeps;
+  private readonly contexts;
+  private activeIndex;
+  private activeContext;
+  private activeBundle;
+  /**
+   * Character management (search, CRUD, pagination, uploads).
+   *
+   * @remarks
+   * Bound to the initial host (production by default) and does not follow an
+   * automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+   * to use these against beta.
+   */
   readonly characters: CharactersService;
-  /** Reference asset management (upload, create, update, list, feed). */
+  /**
+   * Reference asset management (upload, create, update, list, feed).
+   *
+   * @remarks
+   * Bound to the initial host (production by default) and does not follow an
+   * automatic beta fallback. Construct a client with `fallback: { start: 'beta' }`
+   * to use these against beta.
+   */
   readonly references: ReferencesService;
   constructor(options: MageSpaceClientOptions);
+  /** Lazily build (and memoise) the {@link TargetContext} for a chain index. */
+  private getContext;
+  /** Build the generation/history service bundle for a context. */
+  private buildBundle;
+  /** Advance to the next target (sticky). Returns `null` if none or `auto` is off. */
+  private advanceTarget;
+  /** Whether an error is a definitive action-unavailable signal (a fallback trigger). */
+  private shouldFallback;
+  /** Run `op` against the active bundle, switching to the next target once on a trigger. */
+  private withFallback;
   /** Submit a generation job; returns its `historyId`. */
   generate(options: GenerateOptions): Promise<{
     historyId: string;
@@ -694,10 +806,12 @@ declare class MageSpaceClient {
   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. */
+  /** Force re-discovery of the Server Action hashes on the active host. */
   refreshActions(): Promise<ActionSnapshot>;
   /** Return the authenticated user's Firebase uid. */
   getUid(): Promise<string>;
+  /** Return the key of the currently active target (`'production'` or `'beta'`). */
+  getActiveTarget(): TargetKey;
 }
 //#endregion
 //#region lib/errors.d.ts
@@ -716,11 +830,34 @@ declare class AuthError extends MageSpaceError {
 }
 /** Action-hash discovery failures (page/chunk fetch, empty registry). */
 declare class DiscoveryError extends MageSpaceError {
+  /**
+   * `true` when the action name was absent even after a forced re-discovery
+   * (a fallback trigger); `false` for scrape failures (no chunks/no hashes).
+   */
+  readonly notFound: boolean;
   constructor(message: string, options?: {
     cause?: unknown;
+    notFound?: boolean;
   });
 }
-/** A Server Action returned 404, indicating a stale (post-deploy) hash. */
+/**
+ * A required action is unavailable on the active host (a persistent 404 / HTML
+ * fallback that survived one in-place re-discovery). A fallback trigger.
+ */
+declare class ActionUnavailableError extends MageSpaceError {
+  readonly action: string;
+  readonly targetKey: string;
+  constructor(action: string, targetKey: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * A Server Action returned 404, indicating a stale (post-deploy) hash.
+ *
+ * @deprecated Legacy export kept for backward compatibility; no longer thrown.
+ * The current signal for a definitively unavailable action is
+ * {@link ActionUnavailableError}.
+ */
 declare class StaleActionError extends MageSpaceError {
   readonly action: string;
   constructor(action: string, options?: {
@@ -798,5 +935,5 @@ declare const SEED_SNAPSHOT: ActionSnapshot;
 /** 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 };
+export { type ActionCache, type ActionHashes, type ActionName, ActionRegistry, type ActionSnapshot, ActionUnavailableError, type ArchitectureConfig, type AspectRatio, AuthError, type AuthTokens, BETA_TARGET, type Character, type CharacterPage, type CharacterRef, type CharacterSearchResult, CharactersService, type ConfirmOptions, type CreateCharacterInput, type CreateReferenceInput, type Creation, type CreationPage, DEFAULT_TARGET_CHAIN, DiscoveryError, type FallbackOptions, 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, type LogicalAction, MageSpaceClient, type MageSpaceClientOptions, MageSpaceError, type Modality, PRODUCTION_TARGET, type PollStrategy, type Reference, type ReferenceOrder, type ReferencePage, type ReferenceVariant, ReferencesService, type Resolution, RscParseError, SEED_SNAPSHOT, type SearchCharactersOptions, type SessionState, StaleActionError, type Target, type TargetKey, TimeoutError, type UpdateCharacterInput, type UpdateReferenceInput, VERSION, type VideoArchitectureConfig, type VideoAspectRatio, type VideoResolution, type Visibility, type VoiceResult, type WaitOptions, discoverActions, parseFlightRows, parseServerActionResponse, resolveActionName, resolveFlightValue, unwrapResult };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../lib/types.ts","../lib/actions.ts","../lib/http.ts","../lib/auth.ts","../lib/characters.ts","../lib/references.ts","../lib/client.ts","../lib/errors.ts","../lib/rsc.ts","../lib/seed.ts","../lib/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../lib/targets.ts","../lib/types.ts","../lib/actions.ts","../lib/http.ts","../lib/auth.ts","../lib/characters.ts","../lib/references.ts","../lib/client.ts","../lib/errors.ts","../lib/rsc.ts","../lib/seed.ts","../lib/index.ts"],"mappings":"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"}