@sayren/storefront-sdk 0.7.0 → 0.9.0

package/src/payments/index.ts

@@ -0,0 +1,551 @@
+import type { createStorefrontClient } from "../client";
+import {
+  type GuestInfo,
+  type PaymentOption,
+  type PaymentStart,
+  type PaymentStatus,
+  paymentMessageSchema,
+  type ShippingAddressInput,
+} from "../schemas/checkout";
+
+/**
+ * 스토어프론트 결제 — 브라우저 전용(`@sayren/storefront-sdk/payments`).
+ *
+ * ```ts
+ * const payments = createPayments({ client: sdk, returnUrl: `${location.origin}/checkout/return` });
+ * const result = await payments.start(checkoutId, { option, shippingAddress }); // 결제창(팝업)
+ * if (result.status === "COMPLETED") location.assign(`/orders/${result.orderId}`);
+ * ```
+ *
+ * 결제창은 결제 서비스(`payUrl`)가 그린다. SDK는 그 창을 팝업으로 열고 결과 메시지를 받아 결제 상태 조회로 확정한다.
+ * 모바일(또는 `mode: "redirect"`)에서는 현재 탭을 `payUrl`로 보내고, 결제가 끝나면 구매자가 `returnUrl`로 돌아온다 —
+ * 복귀 화면에서 {@link Payments.result}를 부른다.
+ *
+ * **`returnUrl`은 결제를 시작한 페이지와 같은 origin이어야 한다.** 결제 서비스는 팝업 결과 메시지를 복귀 주소의
+ * origin으로 보내므로, origin이 다르면 메시지가 도달하지 않고 결제 상태 조회로만 결과가 정해진다(느려질 뿐 결과는 같다).
+ *
+ * 팝업 메시지는 "끝났다"는 신호일 뿐이다. 결과도 구매자에게 보여 줄 안내 문구도 결제 상태 조회의 `result`·`lastFailure`가
+ * 원천이다 — 메시지의 코드·메시지는 읽지 않는다(누구나 보낼 수 있는 값이다).
+ */
+
+type StorefrontClient = Pick<ReturnType<typeof createStorefrontClient>, "checkout" | "payments">;
+
+/** 결제창을 여는 방식 — `auto`는 모바일이면 리다이렉트, 아니면 팝업이다 */
+export type PaymentMode = "auto" | "popup" | "redirect";
+
+/** `auto` 판정에 쓰는 기기 정보 */
+export interface PaymentDevice {
+  userAgent: string;
+  /** `matchMedia("(pointer: coarse)")` */
+  coarsePointer: boolean;
+  viewportWidth: number;
+}
+
+/** 결제 결과 */
+export type PaymentResult =
+  | {
+      status: "COMPLETED";
+      paymentId: string;
+      /** 만들어진 주문 번호 — 주문 완료 화면으로 보낸다 */
+      orderId: string;
+    }
+  | {
+      /** 구매자가 결제창을 닫았다. 같은 결제를 다른 옵션으로 `retry`할 수 있다 */
+      status: "CANCELED";
+      paymentId: string;
+      code: string;
+      message: string;
+    }
+  | {
+      /** 카드 거절·결제 오류 등. 같은 결제를 다른 옵션으로 `retry`할 수 있다 */
+      status: "FAILED";
+      paymentId: string;
+      code: string;
+      message: string;
+    }
+  | {
+      /** 결과 확인 중 — `getStatus(paymentId)`로 확정될 때까지 조회한다 */
+      status: "PROCESSING";
+      paymentId: string;
+    }
+  | {
+      /** 복귀 주소에 결제 정보가 없다(직접 연 주소 등) */
+      status: "INVALID";
+      message: string;
+    };
+
+/** 결제 서비스 창 — 브라우저에서는 `window.open`이 돌려준 창이다 */
+export interface PaymentPopup {
+  readonly closed: boolean;
+  /** `event.source` 대조용 창 참조 */
+  readonly ref: unknown;
+  /** 결제 서비스 주소로 보낸다 */
+  navigate(url: string): void;
+  close(): void;
+}
+
+/** 결제 서비스가 보낸 postMessage — 브라우저 `MessageEvent`의 필요한 부분만 */
+export interface PaymentPostMessage {
+  data: unknown;
+  origin: string;
+  source: unknown;
+}
+
+/** 브라우저 의존부 — 테스트는 가짜를 넣는다 */
+export interface PaymentsEnv {
+  /** 클릭 시점에 빈 팝업을 연다. 팝업 차단이면 null */
+  openPopup(): PaymentPopup | null;
+  /** 현재 창을 이동시킨다(리다이렉트 결제) */
+  navigate(url: string): void;
+  /** 결제 서비스 메시지 구독 — 해제 함수를 돌려준다 */
+  subscribe(listener: (event: PaymentPostMessage) => void): () => void;
+  /** 복귀 화면의 현재 주소 — `result()`의 기본값 */
+  currentUrl(): string;
+  device(): PaymentDevice;
+  /** 만료 판정에 쓰는 시계. 브라우저 시계가 서버보다 앞서면 팝업 대기가 일찍 끝난다(결과는 PROCESSING) */
+  now(): number;
+  setInterval(handler: () => void, ms: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+/** 복귀 주소에 결제 서비스가 붙이는 쿼리 */
+const RETURN_PAYMENT_ID = "sayrenPaymentId";
+/** 팝업 이름 — 같은 이름으로 열면 결제창이 하나만 뜬다 */
+const POPUP_NAME = "sayren-payment";
+/**
+ * 결제 팝업 크기 — PG 결제창이 안에서 그대로 뜬다. KG이니시스 PC 결제창이 폭 800px 안팎이라 그보다 넓게 연다
+ * (포트원 샌드박스 확인). 화면이 더 작으면 화면에 맞춘다.
+ */
+const POPUP_SIZE = { width: 860, height: 760 };
+
+function popupFeatures(): string {
+  const width = Math.min(POPUP_SIZE.width, window.screen?.availWidth || POPUP_SIZE.width);
+  const height = Math.min(POPUP_SIZE.height, window.screen?.availHeight || POPUP_SIZE.height);
+  return `width=${width},height=${height},resizable=yes,scrollbars=yes`;
+}
+/** 팝업이 메시지 없이 닫혔는지 보는 간격 */
+const POPUP_POLL_MS = 500;
+/** opener를 잃은 팝업 대비 — 결제 상태를 직접 조회하기 시작하는 시점(5초)과 그 뒤 간격(3초) */
+const STATUS_POLL_FIRST_TICKS = 10;
+const STATUS_POLL_EVERY_TICKS = 6;
+/** 좁은 터치 화면은 팝업이 아니라 리다이렉트다 */
+const POPUP_MIN_WIDTH = 820;
+const MOBILE_UA = /Android|iPhone|iPad|iPod|IEMobile|Opera Mini|Mobile/i;
+
+/**
+ * 결제창을 팝업으로 열지 리다이렉트로 열지 정한다 — `auto` 판정 한 곳(순수 함수).
+ * 모바일은 팝업이 탭 전환으로 열리고 간편결제 앱을 거치며 `opener`를 잃으므로 리다이렉트를 쓴다.
+ */
+export function resolvePaymentMode(
+  mode: PaymentMode | undefined,
+  device: PaymentDevice,
+): "popup" | "redirect" {
+  if (mode === "popup" || mode === "redirect") return mode;
+  if (MOBILE_UA.test(device.userAgent)) return "redirect";
+  if (device.coarsePointer && device.viewportWidth > 0 && device.viewportWidth < POPUP_MIN_WIDTH) {
+    return "redirect";
+  }
+  return "popup";
+}
+
+/**
+ * 결제 상태를 화면 결과로 옮긴다 — 결과의 원천은 언제나 `GET /payments/{id}`다(메시지는 신호일 뿐).
+ * 모르는 `result` 값은 확인 중으로 다룬다.
+ */
+export function paymentResultOf(
+  status: PaymentStatus,
+  options: { popupClosed?: boolean } = {},
+): PaymentResult {
+  const { paymentId, result, lastFailure } = status;
+  if (result === "COMPLETED") {
+    return status.orderId
+      ? { status: "COMPLETED", paymentId, orderId: status.orderId }
+      : { status: "PROCESSING", paymentId };
+  }
+  if (result === "CANCELED") {
+    return {
+      status: "CANCELED",
+      paymentId,
+      code: lastFailure?.code ?? "USER_CANCELED",
+      message: lastFailure?.message ?? "결제를 취소했어요",
+    };
+  }
+  if (result === "FAILED" || result === "EXPIRED") {
+    return {
+      status: "FAILED",
+      paymentId,
+      code: lastFailure?.code ?? result,
+      message:
+        lastFailure?.message ??
+        (result === "EXPIRED" ? "결제 요청이 만료됐어요" : "결제에 실패했어요"),
+    };
+  }
+  if (result === "PENDING") {
+    // 결제창이 닫혔는데 아직 결제 전이면 구매자가 닫은 것이다
+    return options.popupClosed
+      ? { status: "CANCELED", paymentId, code: "POPUP_CLOSED", message: "결제창을 닫았어요" }
+      : { status: "PROCESSING", paymentId };
+  }
+  return { status: "PROCESSING", paymentId };
+}
+
+function browserEnv(): PaymentsEnv {
+  return {
+    openPopup() {
+      const popup = window.open("about:blank", POPUP_NAME, popupFeatures());
+      if (!popup) return null;
+      return {
+        get closed() {
+          return popup.closed;
+        },
+        ref: popup,
+        navigate: (url) => {
+          popup.location.href = url;
+        },
+        close: () => popup.close(),
+      };
+    },
+    navigate: (url) => window.location.assign(url),
+    subscribe(listener) {
+      const handler = (event: MessageEvent) =>
+        listener({ data: event.data, origin: event.origin, source: event.source });
+      window.addEventListener("message", handler);
+      return () => window.removeEventListener("message", handler);
+    },
+    currentUrl: () => window.location.href,
+    device: () => ({
+      userAgent: typeof navigator === "undefined" ? "" : navigator.userAgent,
+      coarsePointer:
+        typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches,
+      viewportWidth: window.innerWidth,
+    }),
+    now: () => Date.now(),
+    setInterval: (handler, ms) => setInterval(handler, ms),
+    clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+  };
+}
+
+export interface PaymentsOptions {
+  client: StorefrontClient;
+  /** 결제를 마치면 돌아올 주소(스토어 결제 도메인 안). `start`·`retry`에서 바꿀 수 있다 */
+  returnUrl?: string;
+  env?: PaymentsEnv;
+}
+
+export interface StartOptions {
+  option: PaymentOption;
+  shippingAddress: ShippingAddressInput;
+  guest?: GuestInfo;
+  returnUrl?: string;
+  mode?: PaymentMode;
+  /** 클릭 시점에 {@link Payments.prepareWindow}로 미리 연 창. 폼 검증이 비동기라 클릭 태스크를 넘길 때 쓴다 */
+  window?: PreparedPaymentWindow;
+}
+
+export interface RetryOptions {
+  option: PaymentOption;
+  /** 생략하면 결제 시작 때의 복귀 주소를 쓴다 */
+  returnUrl?: string;
+  mode?: PaymentMode;
+  /** 클릭 시점에 {@link Payments.prepareWindow}로 미리 연 창 */
+  window?: PreparedPaymentWindow;
+}
+
+/** {@link Payments.prepareWindow}가 돌려준 핸들임을 나타내는 표식 — 직접 만든 객체는 받지 않는다 */
+export const PREPARED_WINDOW: unique symbol = Symbol("sayren.payments.preparedWindow");
+
+/**
+ * 클릭 시점에 미리 연 결제창. 결제 시작 API가 서버 함수를 거쳐 느리게 끝나도 팝업 차단에 걸리지 않게
+ * {@link Payments.prepareWindow}로 먼저 열어 두고 {@link Payments.open}(또는 `start`·`retry`의 `window`)에 넘긴다.
+ */
+export interface PreparedPaymentWindow {
+  /** `auto` 판정이 끝난 실제 모드 */
+  readonly mode: "popup" | "redirect";
+  /** 결제 시작에 실패했을 때 미리 연 팝업을 닫는다 */
+  close(): void;
+  /** 이 결제 인스턴스가 연 창이라는 표식. 값은 내부용이다 */
+  readonly [PREPARED_WINDOW]: object;
+}
+
+export interface Payments {
+  /**
+   * 결제 시작 — 결제 세션을 만들고 결제창을 연다. 팝업 모드는 결과가 나올 때까지 기다리고,
+   * 리다이렉트 모드는 페이지가 떠나므로 **끝나지 않는 Promise**를 돌려준다.
+   * 결제 시작 API가 실패하면 미리 연 팝업을 닫고 `ApiError`를 그대로 던진다.
+   */
+  start(checkoutId: string, options: StartOptions): Promise<PaymentResult>;
+  /** 같은 결제를 다른 결제 옵션으로 다시 시도한다 */
+  retry(paymentId: string, options: RetryOptions): Promise<PaymentResult>;
+  /**
+   * 이미 받은 결제 시작 값으로 결제창만 연다 — 결제 시작을 서버 함수로 하는 SSR 앱용.
+   * 클릭 핸들러에서 {@link Payments.prepareWindow}로 창을 먼저 열고 그 핸들을 `window`로 넘긴다.
+   */
+  open(
+    start: PaymentStart,
+    options?: { mode?: PaymentMode; window?: PreparedPaymentWindow },
+  ): Promise<PaymentResult>;
+  /** 클릭 시점에 빈 팝업을 연다(팝업 차단 회피). 반환 핸들을 {@link Payments.open}에 넘긴다 */
+  prepareWindow(options?: { mode?: PaymentMode }): PreparedPaymentWindow;
+  /** 복귀 화면 — 주소의 `sayrenPaymentId`로 결제 상태를 조회해 결과를 만든다 */
+  result(url?: string): Promise<PaymentResult>;
+  /** 결제 상태 조회 — 결과가 `PROCESSING`이면 확정될 때까지 조회한다 */
+  getStatus(paymentId: string): Promise<PaymentStatus>;
+}
+
+interface PreparedWindowInternal extends PreparedPaymentWindow {
+  readonly popup: PaymentPopup | null;
+}
+
+function popupUrl(payUrl: string): string | null {
+  try {
+    const url = new URL(payUrl);
+    url.searchParams.set("mode", "popup");
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+export function createPayments(options: PaymentsOptions): Payments {
+  const { client } = options;
+  const env = options.env ?? browserEnv();
+  /**
+   * 진행 중인 팝업 감시. 팝업은 이름이 같아 다시 열면 같은 창을 쓰므로 감시도 하나만 둔다 —
+   * 새 결제를 시작하면 이전 감시를 끝내고(그 Promise는 `PROCESSING`) 리스너·타이머를 거둔다.
+   */
+  let cancelWatch: (() => void) | null = null;
+  /** 이 인스턴스가 연 창인지 가리는 표식 */
+  const brand: object = {};
+
+  function stopWatch(): void {
+    const cancel = cancelWatch;
+    cancelWatch = null;
+    cancel?.();
+  }
+
+  /**
+   * 결제 서비스는 팝업 결과 메시지를 **복귀 주소(returnUrl)의 origin**으로 보낸다.
+   * 결제를 시작한 페이지와 origin이 다르면 메시지가 도달하지 않아 상태 조회로만 결과가 정해진다.
+   */
+  function warnReturnOrigin(returnUrl: string | undefined, mode: "popup" | "redirect"): void {
+    if (!returnUrl || mode !== "popup") return;
+    try {
+      if (new URL(returnUrl).origin === new URL(env.currentUrl()).origin) return;
+    } catch {
+      return; // 주소를 읽지 못하면 검사하지 않는다
+    }
+    console.warn(
+      `[sayren] returnUrl(${returnUrl})의 origin이 지금 페이지와 달라요 — 결제 서비스는 그 origin으로 결과 메시지를 보내므로 팝업 결과가 도달하지 않고 결제 상태 조회로만 끝나요`,
+    );
+  }
+
+  function prepareWindow(prepareOptions: { mode?: PaymentMode } = {}): PreparedWindowInternal {
+    // 같은 창을 다시 쓰므로 이전 결제의 감시부터 끝낸다
+    stopWatch();
+    const mode = resolvePaymentMode(prepareOptions.mode, env.device());
+    // 팝업 차단이면 창이 null이다 — 리다이렉트로 떨어진다
+    const popup = mode === "popup" ? env.openPopup() : null;
+    return {
+      mode: popup ? "popup" : "redirect",
+      popup,
+      close: () => popup?.close(),
+      [PREPARED_WINDOW]: brand,
+    };
+  }
+
+  /**
+   * 넘겨받은 창 핸들을 확인한다 — 이 인스턴스의 `prepareWindow()`가 돌려준 것만 받는다.
+   * 다른 인스턴스의 것이나 손으로 만든 객체는 창도 감시도 우리 것이 아니라 결제가 조용히 어긋난다.
+   */
+  function resolvePrepared(
+    given: PreparedPaymentWindow | undefined,
+    mode: PaymentMode | undefined,
+  ): PreparedWindowInternal {
+    if (!given) return prepareWindow({ mode });
+    if ((given as Partial<PreparedWindowInternal>)[PREPARED_WINDOW] !== brand) {
+      throw new TypeError(
+        "window는 같은 createPayments의 prepareWindow()가 돌려준 핸들이어야 해요",
+      );
+    }
+    return given as PreparedWindowInternal;
+  }
+
+  /**
+   * 팝업에서 결제가 끝날 때까지 기다린다 — 메시지는 신호, 결과는 상태 조회다.
+   *
+   * 감시는 셋이다. (1) 결제 서비스의 postMessage, (2) 창이 닫혔는지, (3) 결제 상태 직접 조회.
+   * (3)이 있어야 팝업이 `opener`를 잃어(간편결제 앱 전환, 팝업 안에서 복귀 주소로 리다이렉트) 메시지도
+   * 닫힘도 오지 않는 경우에 멈추지 않는다. 어느 경로든 결과는 한 번만 돌려준다.
+   */
+  function awaitPopup(
+    paymentId: string,
+    popup: PaymentPopup,
+    origin: string,
+    expiresAt: string,
+  ): Promise<PaymentResult> {
+    return new Promise<PaymentResult>((resolve) => {
+      let done = false;
+      let ticks = 0;
+      let polling = false;
+      let timer: unknown;
+      let unsubscribe = () => {};
+      let cancelThis: (() => void) | null = null;
+      const deadline = Date.parse(expiresAt);
+
+      const teardown = () => {
+        unsubscribe();
+        env.clearInterval(timer);
+        if (cancelWatch === cancelThis) cancelWatch = null;
+      };
+
+      const finish = (result: PaymentResult) => {
+        if (done) return;
+        done = true;
+        teardown();
+        resolve(result);
+      };
+
+      /** 메시지·닫힘 신호를 받았다 — 결과는 상태 조회로 정한다 */
+      const settle = async (popupClosed: boolean) => {
+        if (done) return;
+        done = true;
+        teardown();
+        try {
+          resolve(paymentResultOf(await client.payments.getStatus(paymentId), { popupClosed }));
+        } catch {
+          resolve({ status: "PROCESSING", paymentId });
+        }
+      };
+
+      // 메시지에서는 `paymentId`만 읽는다 — 결과도 안내 문구(코드·메시지)도 상태 조회의 `result`·`lastFailure`가 원천이다
+      unsubscribe = env.subscribe((event) => {
+        if (event.origin !== origin || event.source !== popup.ref) return;
+        const message = paymentMessageSchema.safeParse(event.data);
+        if (!message.success || message.data.paymentId !== paymentId) return;
+        void settle(false);
+      });
+
+      timer = env.setInterval(() => {
+        if (done) return;
+        if (popup.closed) {
+          void settle(true);
+          return;
+        }
+        if (Number.isFinite(deadline) && env.now() >= deadline) {
+          // 결제 요청이 만료될 때까지 결과를 받지 못했다 — 호출자가 상태를 계속 조회한다
+          finish({ status: "PROCESSING", paymentId });
+          return;
+        }
+        ticks += 1;
+        const since = ticks - STATUS_POLL_FIRST_TICKS;
+        if (polling || since < 0 || since % STATUS_POLL_EVERY_TICKS !== 0) return;
+        polling = true;
+        void client.payments
+          .getStatus(paymentId)
+          .then((status) => {
+            if (done) return;
+            const result = paymentResultOf(status);
+            // 아직 결제 전(PENDING)이거나 확인 중이면 계속 기다린다
+            if (result.status === "PROCESSING") return;
+            // 결과가 확정됐는데 창이 남아 있다 — 닫아 주고 끝낸다
+            try {
+              popup.close();
+            } catch {
+              // 창을 닫지 못해도 결과는 같다
+            }
+            finish(result);
+          })
+          .catch(() => {
+            // 일시적인 조회 실패는 다음 주기에 다시 본다
+          })
+          .finally(() => {
+            polling = false;
+          });
+      }, POPUP_POLL_MS);
+
+      // 다음 결제가 같은 창을 다시 쓰면 이 감시는 끝난다 — 결과는 호출자가 상태 조회로 확인한다
+      cancelThis = () => finish({ status: "PROCESSING", paymentId });
+      cancelWatch = cancelThis;
+    });
+  }
+
+  function open(
+    start: PaymentStart,
+    openOptions: { mode?: PaymentMode; window?: PreparedPaymentWindow } = {},
+  ): Promise<PaymentResult> {
+    // 미리 연 창을 받았으면 prepareWindow가 이미 거뒀다 — 아니면 여기서 이전 감시를 끝낸다
+    stopWatch();
+    const prepared = resolvePrepared(openOptions.window, openOptions.mode);
+    const popup = prepared.popup;
+    const url = popup ? popupUrl(start.payUrl) : null;
+    if (!popup || !url) {
+      popup?.close();
+      env.navigate(start.payUrl);
+      // 페이지가 떠난다 — 결과는 복귀 화면의 result()가 읽는다
+      return new Promise<PaymentResult>(() => {});
+    }
+    popup.navigate(url);
+    return awaitPopup(start.paymentId, popup, new URL(url).origin, start.expiresAt);
+  }
+
+  async function startWith(
+    prepared: PreparedWindowInternal,
+    request: () => Promise<PaymentStart>,
+  ): Promise<PaymentResult> {
+    let start: PaymentStart;
+    try {
+      start = await request();
+    } catch (error) {
+      prepared.close();
+      throw error;
+    }
+    return open(start, { window: prepared });
+  }
+
+  return {
+    prepareWindow,
+    open,
+
+    start(checkoutId, startOptions) {
+      const prepared = resolvePrepared(startOptions.window, startOptions.mode);
+      const returnUrl = startOptions.returnUrl ?? options.returnUrl;
+      if (!returnUrl) {
+        prepared.close();
+        return Promise.reject(
+          new Error("returnUrl이 필요해요 — createPayments 또는 start에 넘겨 주세요"),
+        );
+      }
+      warnReturnOrigin(returnUrl, prepared.mode);
+      return startWith(prepared, () =>
+        client.checkout.startPayment(checkoutId, {
+          option: startOptions.option,
+          shippingAddress: startOptions.shippingAddress,
+          guest: startOptions.guest,
+          returnUrl,
+        }),
+      );
+    },
+
+    retry(paymentId, retryOptions) {
+      const prepared = resolvePrepared(retryOptions.window, retryOptions.mode);
+      const returnUrl = retryOptions.returnUrl ?? options.returnUrl;
+      warnReturnOrigin(returnUrl, prepared.mode);
+      return startWith(prepared, () =>
+        client.payments.retry(paymentId, { option: retryOptions.option, returnUrl }),
+      );
+    },
+
+    getStatus: (paymentId) => client.payments.getStatus(paymentId),
+
+    async result(url) {
+      let paymentId: string | null = null;
+      try {
+        paymentId = new URL(url ?? env.currentUrl()).searchParams.get(RETURN_PAYMENT_ID);
+      } catch {
+        paymentId = null;
+      }
+      if (!paymentId) return { status: "INVALID", message: "결제 정보가 없는 주소예요" };
+      return paymentResultOf(await client.payments.getStatus(paymentId));
+    },
+  };
+}

package/src/schemas/cart.ts

@@ -4,7 +4,7 @@ export const cartItemSchema = z.object({
   cartItemId: z.string(),
   productId: z.string(),
   productName: z.string(),
-  thumbnailUrl: z.url(),
+  thumbnailUrl: z.url().nullable().describe("담은 상품의 대표 이미지. 없으면 null"),
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
   quantity: z.number().int(),

package/src/schemas/catalog.ts

@@ -20,7 +20,7 @@ export const categoryNodeSchema: z.ZodType<CategoryNode> = z.lazy(() =>
 export const productCardSchema = z.object({
   productId: z.string(),
   name: z.string(),
-  thumbnailUrl: z.url(),
+  thumbnailUrl: z.url().nullable().describe("대표 이미지 주소. 등록된 이미지가 없으면 null"),
   salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
   discountedPrice: z
     .number()