@sayren/storefront-sdk 0.6.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 idpAuthorizeRequestSchema, A as pageSchema, B as pgParamsSchema, C as claimTypeSchema, D as claimStatusSchema, E as myClaimSchema, F as createCheckoutRequestSchema, G as productDetailSchema, H as shippingAddressInputSchema, I as guestInfoSchema, J as addCartItemRequestSchema, K as productFacetsSchema, L as paymentMethodSchema, M as checkoutSessionSchema, N as confirmPaymentRequestSchema, O as orderItemStatusSchema, P as confirmPaymentResultSchema, Q as anonymousSessionSchema, R as paymentParamsSchema, S as claimReasonSchema, T as createClaimResultSchema, U as categoryNodeSchema, V as requestPaymentRequestSchema, W as productCardSchema, X as cartSchema, Y as cartItemSchema, Z as updateCartItemRequestSchema, _ as createInquiryRequestSchema, a as publicReviewSchema, at as tokenPairSchema, b as customerInquiryCategorySchema, c as writableReviewSchema, ct as ApiError, d as myOrderSchema, dt as unwrapData, et as idpAuthorizeResponseSchema, f as orderShippingAddressSchema, g as updateProfileRequestSchema, h as memberSchema, i as createReviewResultSchema, it as socialProviderSchema, j as PAYMENT_STATUS_VALUES, k as pageInfoSchema, l as deliveryTrackingSchema, lt as buildQuery, m as memberAddressSchema, n as storefrontStoreSchema, nt as loginRequestSchema, o as reviewSummarySchema, ot as withdrawRequestSchema, p as memberAddressRequestSchema, q as productSortSchema, r as createReviewRequestSchema, rt as signupRequestSchema, s as updateReviewRequestSchema, st as withdrawalBlockedDetailsSchema, t as createStorefrontClient, tt as idpTokenRequestSchema, u as myOrderItemSchema, ut as toApiError, v as publicInquirySchema, w as createClaimRequestSchema, x as customerInquirySchema, y as createCustomerInquiryRequestSchema, z as paymentStatusSchema } from "./client-Do9-LG5X.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, createReviewRequestSchema, createReviewResultSchema, createStorefrontClient, createStorefrontSession, customerInquiryCategorySchema, customerInquirySchema, deliveryTrackingSchema, guestInfoSchema, idpAuthorizeRequestSchema, idpAuthorizeResponseSchema, idpTokenRequestSchema, loginRequestSchema, memberAddressRequestSchema, memberAddressSchema, memberSchema, myClaimSchema, myOrderItemSchema, myOrderSchema, orderItemStatusSchema, orderShippingAddressSchema, pageInfoSchema, pageSchema, paymentMethodSchema, paymentParamsSchema, paymentStatusSchema, pgParamsSchema, productCardSchema, productDetailSchema, productFacetsSchema, productSortSchema, publicInquirySchema, publicReviewSchema, requestPaymentRequestSchema, reviewSummarySchema, shippingAddressInputSchema, signupRequestSchema, socialProviderSchema, storefrontStoreSchema, tokenPairSchema, updateCartItemRequestSchema, updateProfileRequestSchema, updateReviewRequestSchema, 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.6.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/auth/index.ts

@@ -3,6 +3,7 @@ import { ApiError } from "../http";
 import type {
   AnonymousSession,
   LoginRequest,
+  MemberIdentities,
   SignupRequest,
   SocialProvider,
   TokenPair,
@@ -14,6 +15,7 @@ export { ApiError } from "../http";
 export type {
   AnonymousSession,
   LoginRequest,
+  MemberIdentities,
   SignupRequest,
   SocialProvider,
   TokenPair,
@@ -78,7 +80,7 @@ export interface StorefrontAuthOptions {
 }
 
 /**
- * 구매자 인증 — 화면은 스토어프런트가 그리고, 계정 저장과 인증 처리는 sayren이 한다.
+ * 구매자 인증 — 화면은 스토어프론트가 그리고, 계정 저장과 인증 처리는 sayren이 한다.
  * 어느 방식으로 로그인해도 결과는 같은 구매자 토큰(`TokenPair`)이고 `/me/*`·장바구니·주문 API에 그대로 쓴다.
  *
  * 토큰 보관은 앱 몫이다. 서버(loader·action)에서 호출하고 httpOnly 쿠키에 두기를 권한다.
@@ -118,7 +120,7 @@ export function createStorefrontAuth(options: StorefrontAuthOptions) {
     /**
      * 소셜 로그인 시작 — PKCE(S256)와 state를 만들고 공급자 로그인 주소를 받는다. 반환한 `state`·`codeVerifier`를
      * 서버 세션에 보관하고 구매자를 `url`로 보낸다. 로그인을 마치면 `redirectUri`로 `?code=&state=`가 붙어 돌아온다.
-     * `redirectUri`는 스토어프런트 도메인 목록 안이어야 한다
+     * `redirectUri`는 스토어프론트 도메인 목록 안이어야 한다
      */
     async idp(provider: SocialProvider, options: { redirectUri: string }): Promise<IdpStart> {
       const state = randomToken(24);
@@ -146,6 +148,51 @@ export function createStorefrontAuth(options: StorefrontAuthOptions) {
         cartToken: input.cartToken,
       });
     },
+    /** 로그인 수단 — 비밀번호가 있는지, 어떤 소셜 계정이 연결됐는지 */
+    identities(accessToken: string): Promise<MemberIdentities> {
+      return client(accessToken).auth.identities();
+    },
+    /**
+     * 소셜 계정 연결 시작 — 로그인한 구매자에 공급자 계정을 붙인다. `idp()`처럼 `state`·`codeVerifier`를 보관하고
+     * 구매자를 `url`로 보낸다. 돌아오면 `linkIdpCallback()`으로 마무리한다. 연결은 흐름을 시작한 구매자에게만 된다
+     */
+    async linkIdp(
+      accessToken: string,
+      provider: SocialProvider,
+      options: { redirectUri: string },
+    ): Promise<IdpStart> {
+      const state = randomToken(24);
+      const codeVerifier = randomToken(32);
+      const { url } = await client(accessToken).auth.linkIdentityAuthorize(provider, {
+        redirectUri: options.redirectUri,
+        codeChallenge: await s256(codeVerifier),
+        state,
+      });
+      return { url, state, codeVerifier };
+    },
+    /**
+     * 소셜 계정 연결 마무리 — state를 비교하고 code를 바꿔 연결한다. 다른 구매자에 이미 연결된 계정이면
+     * 409 `IDENTITY_IN_USE`, 같은 공급자의 다른 계정을 이미 연결했으면 409 `PROVIDER_ALREADY_LINKED`
+     */
+    linkIdpCallback(
+      accessToken: string,
+      provider: SocialProvider,
+      input: Omit<IdpCallbackInput, "cartToken"> & { error?: string | null },
+    ): Promise<MemberIdentities> {
+      if (input.error) return Promise.reject(new IdpCallbackError(input.error));
+      if (!input.state || input.state !== input.expectedState) {
+        return Promise.reject(new IdpCallbackError("state_mismatch"));
+      }
+      if (!input.code) return Promise.reject(new IdpCallbackError("missing_code"));
+      return client(accessToken).auth.linkIdentity(provider, {
+        code: input.code,
+        codeVerifier: input.codeVerifier,
+      });
+    },
+    /** 소셜 계정 연결 해제 — 마지막 로그인 수단이면 409 `LAST_LOGIN_METHOD` */
+    unlinkIdp(accessToken: string, provider: SocialProvider): Promise<MemberIdentities> {
+      return client(accessToken).auth.unlinkIdentity(provider);
+    },
     /** 토큰 갱신 — refreshToken은 한 번 쓰면 폐기되고 새 쌍이 온다(회전) */
     refresh(refreshToken: string): Promise<TokenPair> {
       return client().auth.refresh(refreshToken);