scrabble-game/ui/src/lib/client.ts

// GatewayClient — the typed facade the screens call. Both the real Connect/
// FlatBuffers transport and the in-memory mock implement it. Domain failures (the
// gateway's result_code) and edge failures (Connect error codes) are normalised
// into a thrown GatewayError carrying a stable `code` the UI maps to an i18n
// message.

import type {
  AccountRef,
  ChatMessage,
  EvalResult,
  FriendCode,
  GameList,
  GameView,
  GcgExport,
  History,
  HintResult,
  Invitation,
  InvitationSettings,
  MatchResult,
  MoveResult,
  Profile,
  ProfileUpdate,
  PushEvent,
  Session,
  StateView,
  Stats,
  Tile,
  Variant,
  WordCheckResult,
} from './model';

/** GatewayError carries a stable code (the gateway result_code, or an edge code). */
export class GatewayError extends Error {
  readonly code: string;
  constructor(code: string, message?: string) {
    super(message ?? code);
    this.name = 'GatewayError';
    this.code = code;
  }
}

/** A tile the player is submitting (rack/blank already resolved to a letter). */
export interface PlacedTile {
  row: number;
  col: number;
  letter: string;
  blank: boolean;
}

/** Unsubscribe handle for the live stream. */
export type Unsubscribe = () => void;

export interface GatewayClient {
  // --- auth (unauthenticated) ---
  authTelegram(initData: string): Promise<Session>;
  authGuest(locale?: string): Promise<Session>;
  authEmailRequest(email: string): Promise<void>;
  authEmailLogin(email: string, code: string): Promise<Session>;

  // --- profile / lists ---
  profileGet(): Promise<Profile>;
  gamesList(): Promise<GameList>;

  // --- lobby ---
  lobbyEnqueue(variant: Variant): Promise<MatchResult>;
  lobbyPoll(): Promise<MatchResult>;

  // --- game ---
  gameState(gameId: string): Promise<StateView>;
  gameHistory(gameId: string): Promise<History>;
  submitPlay(gameId: string, dir: 'H' | 'V', tiles: PlacedTile[]): Promise<MoveResult>;
  pass(gameId: string): Promise<MoveResult>;
  exchange(gameId: string, tiles: string[]): Promise<MoveResult>;
  resign(gameId: string): Promise<MoveResult>;
  hint(gameId: string): Promise<HintResult>;
  evaluate(gameId: string, dir: 'H' | 'V', tiles: PlacedTile[]): Promise<EvalResult>;
  checkWord(gameId: string, word: string): Promise<WordCheckResult>;
  complaint(gameId: string, word: string, note: string): Promise<void>;

  // --- chat ---
  chatPost(gameId: string, body: string): Promise<ChatMessage>;
  chatList(gameId: string): Promise<ChatMessage[]>;
  nudge(gameId: string): Promise<ChatMessage>;

  // --- friends (Stage 8) ---
  friendsList(): Promise<AccountRef[]>;
  friendsIncoming(): Promise<AccountRef[]>;
  friendRequest(accountId: string): Promise<void>;
  friendRespond(requesterId: string, accept: boolean): Promise<void>;
  friendCancel(accountId: string): Promise<void>;
  unfriend(accountId: string): Promise<void>;
  friendCodeIssue(): Promise<FriendCode>;
  friendCodeRedeem(code: string): Promise<AccountRef>;

  // --- blocks (Stage 8) ---
  blocksList(): Promise<AccountRef[]>;
  block(accountId: string): Promise<void>;
  unblock(accountId: string): Promise<void>;

  // --- invitations (Stage 8) ---
  invitationsList(): Promise<Invitation[]>;
  invitationCreate(inviteeIds: string[], settings: InvitationSettings): Promise<Invitation>;
  invitationAccept(invitationId: string): Promise<Invitation>;
  invitationDecline(invitationId: string): Promise<Invitation>;
  invitationCancel(invitationId: string): Promise<void>;

  // --- profile / stats / history (Stage 8) ---
  profileUpdate(p: ProfileUpdate): Promise<Profile>;
  emailBindRequest(email: string): Promise<void>;
  emailBindConfirm(email: string, code: string): Promise<Profile>;
  statsGet(): Promise<Stats>;
  exportGcg(gameId: string): Promise<GcgExport>;

  // --- live stream ---
  subscribe(onEvent: (e: PushEvent) => void, onError?: (err: unknown) => void): Unsubscribe;

  /** Set or clear the bearer token used for authenticated calls and the stream. */
  setToken(token: string | null): void;
}

export type { GameView, Tile };