@sayren/storefront-sdk 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { a as ANALYTICS_VISITOR_HEADER, c as analyticsClientEventSchema, i as ANALYTICS_VISITOR_COOKIE, l as analyticsIdSchema, n as ANALYTICS_SESSION_COOKIE, o as analyticsBatchSchema, r as ANALYTICS_SESSION_HEADER, s as analyticsClientEventNameSchema, t as ANALYTICS_MAX_BATCH_BYTES, u as analyticsServerEventNameSchema } from "./analytics-CgD70OqH.mjs";
 import { t as analyticsIdsFromCookie } from "./analytics-ids-COElZiI3.mjs";
-import { $ as pageSchema, A as createClaimResultSchema, B as paymentStatusSchema, C as publicInquirySchema, D as claimReasonSchema, E as customerInquirySchema, F as confirmPaymentResultSchema, G as productCardSchema, H as requestPaymentRequestSchema, I as createCheckoutRequestSchema, J as productPageSchema, K as productDetailSchema, L as guestInfoSchema, M as PAYMENT_STATUS_VALUES, N as checkoutSessionSchema, O as claimTypeSchema, P as confirmPaymentRequestSchema, Q as pageInfoSchema, R as paymentMethodSchema, S as createInquiryResultSchema, T as customerInquiryCategorySchema, U as shippingAddressInputSchema, V as pgParamsSchema, W as categoryNodeSchema, X as claimStatusSchema, Y as productSortSchema, Z as orderItemStatusSchema, _ as memberAddressSchema, _t as buildQuery, a as publicReviewSchema, at as idpAuthorizeRequestSchema, b as wishlistAddResultSchema, c as updateReviewRequestSchema, ct as linkIdentityRequestSchema, d as deliveryTrackingSchema, dt as signupRequestSchema, et as addCartItemRequestSchema, f as myOrderItemSchema, ft as socialProviderSchema, g as memberAddressRequestSchema, gt as ApiError, h as purchaseDecisionResultSchema, ht as withdrawalBlockedDetailsSchema, i as createReviewResultSchema, it as anonymousSessionSchema, j as myClaimSchema, k as createClaimRequestSchema, l as updateReviewResultSchema, lt as loginRequestSchema, m as orderShippingAddressSchema, mt as withdrawRequestSchema, n as storefrontStoreSchema, nt as cartSchema, o as reviewPageSchema, ot as idpAuthorizeResponseSchema, p as myOrderSchema, pt as tokenPairSchema, q as productFacetsSchema, r as createReviewRequestSchema, rt as updateCartItemRequestSchema, s as reviewSummarySchema, st as idpTokenRequestSchema, t as createStorefrontClient, tt as cartItemSchema, u as writableReviewSchema, ut as memberIdentitiesSchema, v as memberSchema, vt as toApiError, w as createCustomerInquiryRequestSchema, x as createInquiryRequestSchema, y as updateProfileRequestSchema, yt as unwrapData, z as paymentParamsSchema } from "./client-B1uXGefY.mjs";
+import { $ as signupRequestSchema, A as createClaimResultSchema, B as pageInfoSchema, C as publicInquirySchema, D as claimReasonSchema, E as customerInquirySchema, F as productFacetsSchema, G as updateCartItemRequestSchema, H as addCartItemRequestSchema, I as productPageSchema, J as idpAuthorizeResponseSchema, K as anonymousSessionSchema, L as productSortSchema, M as categoryNodeSchema, N as productCardSchema, O as claimTypeSchema, P as productDetailSchema, Q as memberIdentitiesSchema, R as claimStatusSchema, S as createInquiryResultSchema, T as customerInquiryCategorySchema, U as cartItemSchema, V as pageSchema, W as cartSchema, X as linkIdentityRequestSchema, Y as idpTokenRequestSchema, Z as loginRequestSchema, _ as memberAddressSchema, a as publicReviewSchema, at as buildQuery, b as wishlistAddResultSchema, c as updateReviewRequestSchema, d as deliveryTrackingSchema, et as socialProviderSchema, f as myOrderItemSchema, g as memberAddressRequestSchema, h as purchaseDecisionResultSchema, i as createReviewResultSchema, it as ApiError, j as myClaimSchema, k as createClaimRequestSchema, l as updateReviewResultSchema, m as orderShippingAddressSchema, n as storefrontStoreSchema, nt as withdrawRequestSchema, o as reviewPageSchema, ot as toApiError, p as myOrderSchema, q as idpAuthorizeRequestSchema, r as createReviewRequestSchema, rt as withdrawalBlockedDetailsSchema, s as reviewSummarySchema, st as unwrapData, t as createStorefrontClient, tt as tokenPairSchema, u as writableReviewSchema, v as memberSchema, w as createCustomerInquiryRequestSchema, x as createInquiryRequestSchema, y as updateProfileRequestSchema, z as orderItemStatusSchema } from "./client-DwqExvZN.mjs";
+import { _ as pgProviderSchema, a as createCheckoutRequestSchema, b as startPaymentRequestSchema, c as guestInfoSchema, d as paymentMethodSchema, f as paymentOptionKey, g as paymentStatusSchema, h as paymentStartSchema, i as checkoutSessionSchema, l as paymentFailureCategorySchema, m as paymentOptionSchema, n as PAYMENT_STATUS_VALUES, o as easyPayProviderResponseSchema, p as paymentOptionListSchema, r as availablePaymentOptionSchema, s as easyPayProviderSchema, t as PAYMENT_RESULT_VALUES, u as paymentMessageSchema, v as retryPaymentRequestSchema, y as shippingAddressInputSchema } from "./checkout-JFk3b8RG.mjs";
 //#region src/session.ts
 /** 세션 키 상수 — SDK가 소유한다. store-sdk와 겹치지 않는 별도 네임스페이스. */
 const STOREFRONT_SESSION_KEYS = {
@@ -124,4 +125,4 @@ function createStorefrontSession(options) {
 	};
 }
 //#endregion
-export { ANALYTICS_MAX_BATCH_BYTES, ANALYTICS_SESSION_COOKIE, ANALYTICS_SESSION_HEADER, ANALYTICS_VISITOR_COOKIE, ANALYTICS_VISITOR_HEADER, ApiError, PAYMENT_STATUS_VALUES, STOREFRONT_SESSION_KEYS, addCartItemRequestSchema, analyticsBatchSchema, analyticsClientEventNameSchema, analyticsClientEventSchema, analyticsIdSchema, analyticsIdsFromCookie, analyticsServerEventNameSchema, anonymousSessionSchema, buildQuery, cartItemSchema, cartSchema, categoryNodeSchema, checkoutSessionSchema, claimReasonSchema, claimStatusSchema, claimTypeSchema, confirmPaymentRequestSchema, confirmPaymentResultSchema, createCheckoutRequestSchema, createClaimRequestSchema, createClaimResultSchema, createCustomerInquiryRequestSchema, createInquiryRequestSchema, createInquiryResultSchema, createReviewRequestSchema, createReviewResultSchema, createStorefrontClient, createStorefrontSession, customerInquiryCategorySchema, customerInquirySchema, deliveryTrackingSchema, guestInfoSchema, idpAuthorizeRequestSchema, idpAuthorizeResponseSchema, idpTokenRequestSchema, linkIdentityRequestSchema, loginRequestSchema, memberAddressRequestSchema, memberAddressSchema, memberIdentitiesSchema, memberSchema, myClaimSchema, myOrderItemSchema, myOrderSchema, orderItemStatusSchema, orderShippingAddressSchema, pageInfoSchema, pageSchema, paymentMethodSchema, paymentParamsSchema, paymentStatusSchema, pgParamsSchema, productCardSchema, productDetailSchema, productFacetsSchema, productPageSchema, productSortSchema, publicInquirySchema, publicReviewSchema, purchaseDecisionResultSchema, requestPaymentRequestSchema, reviewPageSchema, reviewSummarySchema, shippingAddressInputSchema, signupRequestSchema, socialProviderSchema, storefrontStoreSchema, tokenPairSchema, updateCartItemRequestSchema, updateProfileRequestSchema, updateReviewRequestSchema, updateReviewResultSchema, wishlistAddResultSchema, withdrawRequestSchema, withdrawalBlockedDetailsSchema, writableReviewSchema };
+export { ANALYTICS_MAX_BATCH_BYTES, ANALYTICS_SESSION_COOKIE, ANALYTICS_SESSION_HEADER, ANALYTICS_VISITOR_COOKIE, ANALYTICS_VISITOR_HEADER, ApiError, PAYMENT_RESULT_VALUES, PAYMENT_STATUS_VALUES, STOREFRONT_SESSION_KEYS, addCartItemRequestSchema, analyticsBatchSchema, analyticsClientEventNameSchema, analyticsClientEventSchema, analyticsIdSchema, analyticsIdsFromCookie, analyticsServerEventNameSchema, anonymousSessionSchema, availablePaymentOptionSchema, buildQuery, cartItemSchema, cartSchema, categoryNodeSchema, checkoutSessionSchema, claimReasonSchema, claimStatusSchema, claimTypeSchema, createCheckoutRequestSchema, createClaimRequestSchema, createClaimResultSchema, createCustomerInquiryRequestSchema, createInquiryRequestSchema, createInquiryResultSchema, createReviewRequestSchema, createReviewResultSchema, createStorefrontClient, createStorefrontSession, customerInquiryCategorySchema, customerInquirySchema, deliveryTrackingSchema, easyPayProviderResponseSchema, easyPayProviderSchema, guestInfoSchema, idpAuthorizeRequestSchema, idpAuthorizeResponseSchema, idpTokenRequestSchema, linkIdentityRequestSchema, loginRequestSchema, memberAddressRequestSchema, memberAddressSchema, memberIdentitiesSchema, memberSchema, myClaimSchema, myOrderItemSchema, myOrderSchema, orderItemStatusSchema, orderShippingAddressSchema, pageInfoSchema, pageSchema, paymentFailureCategorySchema, paymentMessageSchema, paymentMethodSchema, paymentOptionKey, paymentOptionListSchema, paymentOptionSchema, paymentStartSchema, paymentStatusSchema, pgProviderSchema, productCardSchema, productDetailSchema, productFacetsSchema, productPageSchema, productSortSchema, publicInquirySchema, publicReviewSchema, purchaseDecisionResultSchema, retryPaymentRequestSchema, reviewPageSchema, reviewSummarySchema, shippingAddressInputSchema, signupRequestSchema, socialProviderSchema, startPaymentRequestSchema, storefrontStoreSchema, tokenPairSchema, updateCartItemRequestSchema, updateProfileRequestSchema, updateReviewRequestSchema, updateReviewResultSchema, wishlistAddResultSchema, withdrawRequestSchema, withdrawalBlockedDetailsSchema, writableReviewSchema };

package/dist/payments/index.d.mts

@@ -0,0 +1,166 @@
+import { A as createStorefrontClient, Ht as PaymentOption, Pt as GuestInfo, Ut as PaymentStart, Wt as PaymentStatus, qt as ShippingAddressInput } from "../index-BRXStiK2.mjs";
+//#region src/payments/index.d.ts
+/**
+ * 스토어프론트 결제 — 브라우저 전용(`@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;
+}
+/**
+ * 결제창을 팝업으로 열지 리다이렉트로 열지 정한다 — `auto` 판정 한 곳(순수 함수).
+ * 모바일은 팝업이 탭 전환으로 열리고 간편결제 앱을 거치며 `opener`를 잃으므로 리다이렉트를 쓴다.
+ */
+export declare function resolvePaymentMode(mode: PaymentMode | undefined, device: PaymentDevice): "popup" | "redirect";
+/**
+ * 결제 상태를 화면 결과로 옮긴다 — 결과의 원천은 언제나 `GET /payments/{id}`다(메시지는 신호일 뿐).
+ * 모르는 `result` 값은 확인 중으로 다룬다.
+ */
+export declare function paymentResultOf(status: PaymentStatus, options?: {
+  popupClosed?: boolean;
+}): PaymentResult;
+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 declare const PREPARED_WINDOW: unique symbol;
+/**
+ * 클릭 시점에 미리 연 결제창. 결제 시작 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>;
+}
+export declare function createPayments(options: PaymentsOptions): Payments;
+//#endregion

package/dist/payments/index.mjs

@@ -0,0 +1,310 @@
+import { u as paymentMessageSchema } from "../checkout-JFk3b8RG.mjs";
+//#region src/payments/index.ts
+/** 복귀 주소에 결제 서비스가 붙이는 쿼리 */
+const RETURN_PAYMENT_ID = "sayrenPaymentId";
+/** 팝업 이름 — 같은 이름으로 열면 결제창이 하나만 뜬다 */
+const POPUP_NAME = "sayren-payment";
+const POPUP_FEATURES = "width=500,height=720,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`를 잃으므로 리다이렉트를 쓴다.
+*/
+function resolvePaymentMode(mode, device) {
+	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` 값은 확인 중으로 다룬다.
+*/
+function paymentResultOf(status, options = {}) {
+	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() {
+	return {
+		openPopup() {
+			const popup = window.open("about:blank", POPUP_NAME, POPUP_FEATURES);
+			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) => 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)
+	};
+}
+/** {@link Payments.prepareWindow}가 돌려준 핸들임을 나타내는 표식 — 직접 만든 객체는 받지 않는다 */
+const PREPARED_WINDOW = Symbol("sayren.payments.preparedWindow");
+function popupUrl(payUrl) {
+	try {
+		const url = new URL(payUrl);
+		url.searchParams.set("mode", "popup");
+		return url.toString();
+	} catch {
+		return null;
+	}
+}
+function createPayments(options) {
+	const { client } = options;
+	const env = options.env ?? browserEnv();
+	/**
+	* 진행 중인 팝업 감시. 팝업은 이름이 같아 다시 열면 같은 창을 쓰므로 감시도 하나만 둔다 —
+	* 새 결제를 시작하면 이전 감시를 끝내고(그 Promise는 `PROCESSING`) 리스너·타이머를 거둔다.
+	*/
+	let cancelWatch = null;
+	/** 이 인스턴스가 연 창인지 가리는 표식 */
+	const brand = {};
+	function stopWatch() {
+		const cancel = cancelWatch;
+		cancelWatch = null;
+		cancel?.();
+	}
+	/**
+	* 결제 서비스는 팝업 결과 메시지를 **복귀 주소(returnUrl)의 origin**으로 보낸다.
+	* 결제를 시작한 페이지와 origin이 다르면 메시지가 도달하지 않아 상태 조회로만 결과가 정해진다.
+	*/
+	function warnReturnOrigin(returnUrl, mode) {
+		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 = {}) {
+		stopWatch();
+		const popup = resolvePaymentMode(prepareOptions.mode, env.device()) === "popup" ? env.openPopup() : null;
+		return {
+			mode: popup ? "popup" : "redirect",
+			popup,
+			close: () => popup?.close(),
+			[PREPARED_WINDOW]: brand
+		};
+	}
+	/**
+	* 넘겨받은 창 핸들을 확인한다 — 이 인스턴스의 `prepareWindow()`가 돌려준 것만 받는다.
+	* 다른 인스턴스의 것이나 손으로 만든 객체는 창도 감시도 우리 것이 아니라 결제가 조용히 어긋난다.
+	*/
+	function resolvePrepared(given, mode) {
+		if (!given) return prepareWindow({ mode });
+		if (given[PREPARED_WINDOW] !== brand) throw new TypeError("window는 같은 createPayments의 prepareWindow()가 돌려준 핸들이어야 해요");
+		return given;
+	}
+	/**
+	* 팝업에서 결제가 끝날 때까지 기다린다 — 메시지는 신호, 결과는 상태 조회다.
+	*
+	* 감시는 셋이다. (1) 결제 서비스의 postMessage, (2) 창이 닫혔는지, (3) 결제 상태 직접 조회.
+	* (3)이 있어야 팝업이 `opener`를 잃어(간편결제 앱 전환, 팝업 안에서 복귀 주소로 리다이렉트) 메시지도
+	* 닫힘도 오지 않는 경우에 멈추지 않는다. 어느 경로든 결과는 한 번만 돌려준다.
+	*/
+	function awaitPopup(paymentId, popup, origin, expiresAt) {
+		return new Promise((resolve) => {
+			let done = false;
+			let ticks = 0;
+			let polling = false;
+			let timer;
+			let unsubscribe = () => {};
+			let cancelThis = null;
+			const deadline = Date.parse(expiresAt);
+			const teardown = () => {
+				unsubscribe();
+				env.clearInterval(timer);
+				if (cancelWatch === cancelThis) cancelWatch = null;
+			};
+			const finish = (result) => {
+				if (done) return;
+				done = true;
+				teardown();
+				resolve(result);
+			};
+			/** 메시지·닫힘 신호를 받았다 — 결과는 상태 조회로 정한다 */
+			const settle = async (popupClosed) => {
+				if (done) return;
+				done = true;
+				teardown();
+				try {
+					resolve(paymentResultOf(await client.payments.getStatus(paymentId), { popupClosed }));
+				} catch {
+					resolve({
+						status: "PROCESSING",
+						paymentId
+					});
+				}
+			};
+			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;
+				settle(false);
+			});
+			timer = env.setInterval(() => {
+				if (done) return;
+				if (popup.closed) {
+					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;
+				client.payments.getStatus(paymentId).then((status) => {
+					if (done) return;
+					const result = paymentResultOf(status);
+					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, openOptions = {}) {
+		stopWatch();
+		const popup = resolvePrepared(openOptions.window, openOptions.mode).popup;
+		const url = popup ? popupUrl(start.payUrl) : null;
+		if (!popup || !url) {
+			popup?.close();
+			env.navigate(start.payUrl);
+			return new Promise(() => {});
+		}
+		popup.navigate(url);
+		return awaitPopup(start.paymentId, popup, new URL(url).origin, start.expiresAt);
+	}
+	async function startWith(prepared, request) {
+		let start;
+		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(/* @__PURE__ */ 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 = 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));
+		}
+	};
+}
+//#endregion
+export { PREPARED_WINDOW, createPayments, paymentResultOf, resolvePaymentMode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/storefront-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -18,6 +18,11 @@
       "development": "./src/auth/index.ts",
       "types": "./dist/auth/index.d.mts",
       "default": "./dist/auth/index.mjs"
+    },
+    "./payments": {
+      "development": "./src/payments/index.ts",
+      "types": "./dist/payments/index.d.mts",
+      "default": "./dist/payments/index.mjs"
     }
   },
   "dependencies": {
@@ -42,7 +47,7 @@
     "dist",
     "src"
   ],
-  "description": "sayren 스토어프론트 API SDK — zod 스키마 + fetch 클라이언트",
+  "description": "sayren 스토어프론트 API SDK — zod 스키마 + fetch 클라이언트 + 브라우저 결제·분석·인증 모듈",
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",

package/src/client.ts

@@ -36,13 +36,13 @@ import {
 import {
   type CreateCheckoutRequest,
   checkoutSessionSchema,
-  confirmPaymentRequestSchema,
-  confirmPaymentResultSchema,
   createCheckoutRequestSchema,
-  paymentParamsSchema,
+  paymentStartSchema,
   paymentStatusSchema,
-  type RequestPaymentRequest,
-  requestPaymentRequestSchema,
+  type RetryPaymentRequest,
+  retryPaymentRequestSchema,
+  type StartPaymentRequest,
+  startPaymentRequestSchema,
 } from "./schemas/checkout";
 import {
   type CreateClaimRequest,
@@ -272,48 +272,41 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
           body: createCheckoutRequestSchema.parse(body),
         }),
       /**
-       * 결제 시작 — 결제 세션을 만들고 결제 팝업 URL(`pgParams.popupUrl`)을 돌려준다.
-       * `pgProvider`는 첫 결제 시도의 PG다(현재 `tosspayments`·`portone`, 새 PG가 추가돼도 파싱은 깨지지 않는다).
+       * `POST /checkout/{checkoutId}/payment` — 결제 시작. 배송지와 결제 옵션(`paymentOptions` 항목 또는 직접 쓴 옵션)으로
+       * 결제 세션·첫 시도를 만들고 결제 서비스 주소(`payUrl`)를 돌려준다. 그 주소를 열어 결제를 진행하는 것은
+       * `@sayren/storefront-sdk/payments`의 `createPayments().start()`다 — 이 메서드는 값만 받는다.
        *
-       * PG 관련 에러(`ApiError.code`) — 둘 다 "결제 수단 준비 중" 안내를 권장한다.
-       * - 409 `PAYMENT_NOT_CONFIGURED`: 스토어에 사용 중인 PG가 없다. 결제 세션을 만들지 않는다
-       * - 503 `PAYMENT_PROVIDER_UNAVAILABLE`: 사용 중인 PG가 모두 준비 장애다. 잠시 후 재시도할 수 있다
+       * 에러(`ApiError.code`):
+       * - 409 `PAYMENT_OPTION_UNAVAILABLE`: 이 스토어에서 쓸 수 없는 옵션. `details.paymentOptions`에 지금 목록
+       * - 409 `PAYMENT_NOT_CONFIGURED`: 사용 중인 PG가 없다
+       * - 400 `RETURN_URL_NOT_ALLOWED`: `returnUrl`이 https가 아니거나(테스트 결제의 localhost는 예외),
+       *   스토어가 결제 도메인을 등록했는데 그 안이 아니다. 등록하지 않았으면 https 주소는 모두 받는다
+       * - 503 `PAYMENT_PROVIDER_UNAVAILABLE`: 고른 PG의 결제창을 준비하지 못했다(다른 옵션으로 다시 시도)
        */
-      requestPayment: (checkoutId: string, body: RequestPaymentRequest) =>
-        http.request("POST", path`/checkout/${checkoutId}/payment`, paymentParamsSchema, {
-          body: requestPaymentRequestSchema.parse(body),
-        }),
-      /**
-       * 결제 승인 확정 — 같은 `paymentId + pgToken` 재호출은 저장된 결과를 돌려준다(멱등).
-       * `options.attemptId`는 결제창이 돌려준 주문번호(시도 id)이고, 생략하면 현재 시도를 승인한다.
-       *
-       * 요청 본문은 보내기 전에 `confirmPaymentRequestSchema`로 검증한다. 빈 `pgToken`처럼 형식이 틀리면
-       * 요청을 보내지 않고 **동기로 ZodError를 던진다**(Promise reject 아님 — 다른 메서드의 요청 검증과 같다).
-       *
-       * 카드 거절(402 `PG_DECLINED` 등)·402 `PAYMENT_NOT_APPROVED`·502 `PG_REQUEST_FAILED`·
-       * 503 `PG_CREDENTIALS_UNAVAILABLE` 뒤에도 세션은 `pending`으로 남아 다시 시도할 수 있다.
-       * 409 `LATE_APPROVAL_CANCELED`(미승인으로 판정된 뒤 늦게 온 승인을 서버가 PG 취소함)도 세션이 `pending`으로 남는다.
-       * 409 `PAYMENT_RESULT_UNKNOWN`은 결과 확인 중이라 재시도하면 안 된다. 그 밖의 409:
-       * `ATTEMPT_NOT_CURRENT`·`INVALID_ATTEMPT_STATE`·`PAYMENT_SESSION_OUTDATED`·`PG_AMOUNT_MISMATCH`.
-       * 503 `PG_MERCHANT_MISMATCH`: 승인 시도의 가맹점과 현재 저장된 자격 증명의 가맹점이 다르다.
-       */
-      confirmPayment: (paymentId: string, pgToken: string, options?: { attemptId?: string }) =>
-        http.request("POST", path`/payments/${paymentId}/confirm`, confirmPaymentResultSchema, {
-          body: confirmPaymentRequestSchema.parse({ pgToken, attemptId: options?.attemptId }),
+      startPayment: (checkoutId: string, body: StartPaymentRequest) =>
+        http.request("POST", path`/checkout/${checkoutId}/payment`, paymentStartSchema, {
+          body: startPaymentRequestSchema.parse(body),
         }),
     },
 
     payments: {
       /**
-       * `GET /storefront/v1/payments/{paymentId}` — 결제 상태 조회. 결제 팝업이 결과(postMessage)를 알리지 못하고 닫혔을 때
-       * 부모 창이 `expiresAt`까지 폴링해 결과를 확인한다. `completed`면 `orderId`로 완료 화면, `processing`이면 계속 폴링,
-       * `pending`이면 기존 안내, `failed`·`expired`면 실패 안내다. TTL이 지난 `pending`은 `expired`로 보고된다.
-       * `testPayment`는 완료면 주문 플래그, 아니면 세션 환경이다.
+       * `GET /storefront/v1/payments/{paymentId}` — 결제 상태 조회. 복귀 화면에서 결과가 확인 중(`processing`)이면
+       * `expiresAt`까지 폴링한다. `completed`면 `orderId`로 완료 화면, `failed`·`expired`면 실패 안내다.
+       * TTL이 지난 `pending`은 `expired`로 보고된다. `testPayment`는 완료면 주문 플래그, 아니면 세션 환경이다.
        *
        * 에러: 404 `PAYMENT_NOT_FOUND`(없음·다른 스토어) · 410 `STORE_CLOSED` · 503 `STORE_SUSPENDED`
        */
       getStatus: (paymentId: string) =>
         http.request("GET", path`/payments/${paymentId}`, paymentStatusSchema),
+      /**
+       * `POST /payments/{paymentId}/attempts` — 같은 결제에서 다른 결제 옵션으로 다시 시도한다. 새 시도의 결제창 값을
+       * 돌려준다. 승인 중이거나 결과 확인 중이면 409 `PAYMENT_IN_PROGRESS`다.
+       */
+      retry: (paymentId: string, body: RetryPaymentRequest) =>
+        http.request("POST", path`/payments/${paymentId}/attempts`, paymentStartSchema, {
+          body: retryPaymentRequestSchema.parse(body),
+        }),
     },
 
     myOrders: {