《移动游戏产品的架构·商业化与发行工程》6.2 广告 SDK 生命周期与填充失败兜底

// file: src/biz/ad-lifecycle.ts
// tier: L1
// verify: node --test test/biz/ad-lifecycle.test.ts

export type AdStatus =
  | "idle"
  | "loading"
  | "ready"
  | "showing"
  | "completed"
  | "closed"
  | "failed";

export type AdEventType =
  | "load-request"
  | "loaded"
  | "load-failed"
  | "timeout"
  | "show"
  | "completed"
  | "closed";

export interface AdEvent {
  readonly type: AdEventType;
  readonly detail?: string;
}

export interface AdSession {
  readonly id: string;
  readonly status: AdStatus;
  readonly attempts: number;
  readonly rewardGranted: boolean;
  readonly lastError: string | null;
}

export type FallbackAction = "retry" | "compensate" | "drop";

export interface FallbackOptions {
  readonly maxAttempts: number;
  readonly canRetry: boolean;
  readonly canCompensate: boolean;
}

export function createSession(id: string): AdSession {
  if (typeof id !== "string" || id.trim() === "") {
    throw new Error("session id must be a non-empty string");
  }
  return { id, status: "idle", attempts: 0, rewardGranted: false, lastError: null };
}

export function isTerminal(status: AdStatus): boolean {
  return status === "completed" || status === "closed" || status === "failed";
}

export function reduce(session: AdSession, event: AdEvent): AdSession {
  const type = event.type;

  if (type === "load-request") {
    if (session.status === "loading" || session.status === "ready" || session.status === "showing") {
      return session;
    }
    return {
      ...session,
      status: "loading",
      attempts: session.attempts + 1,
      rewardGranted: false,
      lastError: null,
    };
  }

  if (type === "loaded") {
    return session.status === "loading" ? { ...session, status: "ready" } : session;
  }

  if (type === "load-failed") {
    return session.status === "loading"
      ? { ...session, status: "failed", lastError: event.detail ?? "load-failed" }
      : session;
  }

  if (type === "timeout") {
    return session.status === "loading" || session.status === "ready"
      ? { ...session, status: "failed", lastError: "timeout" }
      : session;
  }

  if (type === "show") {
    return session.status === "ready" ? { ...session, status: "showing" } : session;
  }

  if (type === "completed") {
    if (session.status !== "showing" && session.status !== "closed") {
      return session;
    }
    return { ...session, status: "completed", rewardGranted: true };
  }

  if (type === "closed") {
    return session.status === "showing" ? { ...session, status: "closed" } : session;
  }

  throw new Error(`unknown ad event: ${String(type)}`);
}

export function shouldGrant(session: AdSession): boolean {
  return session.status === "completed" && session.rewardGranted;
}

export function fallbackFor(session: AdSession, options: FallbackOptions): FallbackAction {
  if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 0) {
    throw new Error(`maxAttempts must be a non-negative integer, got ${options.maxAttempts}`);
  }
  if (session.status !== "failed") {
    return "drop";
  }
  if (options.canRetry && session.attempts < options.maxAttempts) {
    return "retry";
  }
  if (options.canCompensate) {
    return "compensate";
  }
  return "drop";
}

export function formatSession(session: AdSession): string {
  const reward = session.rewardGranted ? "yes" : "no";
  const error = session.lastError ?? "none";
  return `${session.id} status=${session.status} reward=${reward} attempts=${session.attempts} error=${error}`;
}