@sayren/storefront-sdk 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/storefront-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -13,6 +13,11 @@
       "development": "./src/analytics/index.ts",
       "types": "./dist/analytics/index.d.mts",
       "default": "./dist/analytics/index.mjs"
+    },
+    "./auth": {
+      "development": "./src/auth/index.ts",
+      "types": "./dist/auth/index.d.mts",
+      "default": "./dist/auth/index.mjs"
     }
   },
   "dependencies": {

package/src/analytics/index.ts

@@ -84,6 +84,11 @@ const SESSION_CAMPAIGN_COOKIE = "sy_scmp";
 const MAX_BATCH = 50;
 /** 이벤트 이름당 분당 상한 — 무한 루프 버그가 트래픽을 만들지 못하게 */
 const PER_NAME_PER_MINUTE = 30;
+/**
+ * 전체 분당 상한 — 서버의 방문자당 분당 한도(120)보다 낮게 둬, SDK가 보낸 이벤트가 서버 한도에 걸려
+ * 조용히 버려지지 않게 한다(이름당 상한만으로는 이름 5종 × 30 = 150까지 갈 수 있다).
+ */
+const TOTAL_PER_MINUTE = 100;
 const MAX_QUEUE = 500;
 
 const DEV_HOST =
@@ -110,9 +115,15 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
   let visibleMs = 0;
   let engagementSent = false;
   let firstPage = true;
+  /**
+   * 지금 페이지뷰를 보냈는가 — 상한으로 페이지뷰가 버려졌으면 그 페이지의 상품 조회·목록·검색·체류도 보내지 않는다.
+   * 그러지 않으면 존재하지 않는 페이지뷰를 가리키는 이벤트가 남는다.
+   */
+  let pageAccepted = false;
   const seen = new Set<string>();
   let rateMinute = -1;
   const perName = new Map<string, number>();
+  let totalThisMinute = 0;
   const cleanups: Array<() => void> = [];
 
   const campaignOf = (href: string) => {
@@ -147,20 +158,24 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
     if (minute !== rateMinute) {
       rateMinute = minute;
       perName.clear();
+      totalThisMinute = 0;
     }
     const used = perName.get(name) ?? 0;
-    if (used >= PER_NAME_PER_MINUTE) return false;
+    if (used >= PER_NAME_PER_MINUTE || totalThisMinute >= TOTAL_PER_MINUTE) return false;
     perName.set(name, used + 1);
+    totalThisMinute += 1;
     return true;
   };
 
-  const push = (event: Pending, dedupeKey: string) => {
-    if (!enabled || consent === "denied") return;
-    if (seen.has(dedupeKey) || !allowRate(event.name)) return;
+  /** 큐에 넣었으면 true — 중복·상한·거부로 버리면 false */
+  const push = (event: Pending, dedupeKey: string): boolean => {
+    if (!enabled || consent === "denied") return false;
+    if (seen.has(dedupeKey) || !allowRate(event.name)) return false;
     seen.add(dedupeKey);
     if (queue.length >= MAX_QUEUE) queue.shift();
     queue.push(event);
     if (queue.length >= MAX_BATCH) flush();
+    return true;
   };
 
   const flush = () => {
@@ -183,7 +198,7 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
 
   /** 지금 페이지의 체류를 한 번 보낸다(이동·숨김·닫힘 중 먼저 오는 때) */
   const endPage = () => {
-    if (!pageViewId || engagementSent) return;
+    if (!pageViewId || engagementSent || !pageAccepted) return;
     if (visibleSince !== null) {
       visibleMs += env.now() - visibleSince;
       visibleSince = env.visible() ? env.now() : null;
@@ -219,8 +234,7 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
     visibleSince = env.visible() ? env.now() : null;
     engagementSent = false;
     const referrer = firstPage ? env.referrer() : "";
-    firstPage = false;
-    push(
+    pageAccepted = push(
       {
         name: "page_view",
         occurredAt: occurredAt(),
@@ -230,6 +244,8 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
       },
       `page:${pageViewId}`,
     );
+    // 외부 유입(리퍼러)은 실제로 보낸 첫 페이지뷰에만 싣는다 — 거부 중 버린 페이지뷰가 가져가지 않게
+    if (pageAccepted) firstPage = false;
   };
 
   /** 프리렌더·숨은 탭은 화면에 보이는 순간 첫 페이지뷰를 보낸다 */
@@ -268,6 +284,7 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
   return {
     track(input) {
       if (!pageViewId) startPage();
+      if (!pageAccepted) return; // 페이지뷰가 버려진 페이지의 행동은 보내지 않는다
       const common = { occurredAt: occurredAt(), url: env.href(), pageViewId };
       switch (input.name) {
         case "product_view":
@@ -308,7 +325,14 @@ export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv
     setConsent(next) {
       consent = next;
       if (next === "denied") queue = [];
-      if (next === "granted") flush();
+      if (next === "granted") {
+        // 거부 중에 연 페이지는 페이지뷰가 없다 — 동의한 지금 그 페이지를 새로 센다
+        if (pageViewId && !pageAccepted && options.autoPageViews !== false) {
+          pageKey = "";
+          startPage();
+        }
+        flush();
+      }
     },
     ids: () => (enabled ? ensureIds() : null),
     flush,

package/src/auth/index.ts

@@ -0,0 +1,74 @@
+import { createStorefrontClient } from "../client";
+import { ApiError } from "../http";
+import type { AnonymousSession, LoginRequest, SignupRequest, TokenPair } from "../schemas/auth";
+
+/** 실패는 모두 이 클래스다 — 메인 엔트리의 `ApiError`와 같은 클래스라 어느 쪽으로 `instanceof`해도 된다 */
+export { ApiError } from "../http";
+export type { AnonymousSession, LoginRequest, SignupRequest, TokenPair } from "../schemas/auth";
+
+export interface StorefrontAuthOptions {
+  /** 예: https://api.sayren.app/storefront/v1 */
+  baseUrl: string;
+  /** 테넌트 스토어 코드 — `X-Store-Code` 헤더로 보낸다 */
+  storeCode: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * 구매자 인증 — 화면은 스토어프런트가 그리고, 계정 저장과 인증 처리는 sayren이 한다.
+ * 어느 방식으로 로그인해도 결과는 같은 구매자 토큰(`TokenPair`)이고 `/me/*`·장바구니·주문 API에 그대로 쓴다.
+ *
+ * 토큰 보관은 앱 몫이다. 서버(loader·action)에서 호출하고 httpOnly 쿠키에 두기를 권한다.
+ *
+ * ```ts
+ * const auth = createStorefrontAuth({ baseUrl, storeCode });
+ * const guest = await auth.anonymous();                         // 비회원: 장바구니 토큰
+ * const tokens = await auth.session({ email, password, cartToken: guest.cartToken });
+ * ```
+ */
+export function createStorefrontAuth(options: StorefrontAuthOptions) {
+  const client = (accessToken?: string) =>
+    createStorefrontClient({
+      baseUrl: options.baseUrl,
+      storeCode: options.storeCode,
+      accessToken,
+      fetch: options.fetch,
+    });
+
+  return {
+    /**
+     * 비회원 익명 세션 — 구매자 계정을 만들지 않는다. `cartToken`을 `X-Cart-Token`으로 보내면 장바구니·
+     * 비회원 주문이 쌓이고, `session()`·`signUp()`에 실으면 회원 장바구니로 병합된 뒤 닫힌다.
+     * 마지막 활동 후 30일이 지나면 만료된다.
+     */
+    anonymous(): Promise<AnonymousSession> {
+      return client().auth.anonymous();
+    },
+    /** 이메일·비밀번호 로그인. `cartToken`을 주면 비회원 장바구니를 병합한다 */
+    session(body: LoginRequest): Promise<TokenPair> {
+      return client().auth.login(body);
+    },
+    /** 회원가입 — 가입과 동시에 로그인 토큰을 받는다. `cartToken`을 주면 장바구니를 병합한다 */
+    signUp(body: SignupRequest): Promise<TokenPair> {
+      return client().auth.signup(body);
+    },
+    /** 토큰 갱신 — refreshToken은 한 번 쓰면 폐기되고 새 쌍이 온다(회전) */
+    refresh(refreshToken: string): Promise<TokenPair> {
+      return client().auth.refresh(refreshToken);
+    },
+    /**
+     * 로그아웃 — 이 구매자의 refreshToken을 모두 폐기한다. 앱은 보관한 토큰을 지운다.
+     * 액세스 토큰이 이미 만료됐으면(401) 서버에서 할 일이 없으므로 성공으로 본다.
+     */
+    async signOut(accessToken: string): Promise<void> {
+      try {
+        await client(accessToken).auth.logout();
+      } catch (error) {
+        if (error instanceof ApiError && error.status === 401) return;
+        throw error;
+      }
+    },
+  };
+}
+
+export type StorefrontAuth = ReturnType<typeof createStorefrontAuth>;

package/src/client.ts

@@ -2,7 +2,12 @@ import { z } from "zod";
 import { createHttp, path, type Query, resolveToken, type TokenSource } from "./http";
 import { ANALYTICS_SESSION_HEADER, ANALYTICS_VISITOR_HEADER } from "./schemas/analytics";
 import type { LoginRequest, SignupRequest } from "./schemas/auth";
-import { loginRequestSchema, signupRequestSchema, tokenPairSchema } from "./schemas/auth";
+import {
+  anonymousSessionSchema,
+  loginRequestSchema,
+  signupRequestSchema,
+  tokenPairSchema,
+} from "./schemas/auth";
 import {
   type AddCartItemRequest,
   addCartItemRequestSchema,
@@ -163,6 +168,8 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
       return session.userinfo();
     },
     auth: {
+      /** 비회원 익명 세션 발급 — 응답의 cartToken을 `cartToken` 옵션(X-Cart-Token)으로 쓴다 */
+      anonymous: () => http.request("POST", "/auth/anonymous", anonymousSessionSchema),
       signup: (body: SignupRequest) =>
         http.request("POST", "/auth/signup", tokenPairSchema, {
           body: signupRequestSchema.parse(body),

package/src/schemas/auth.ts

@@ -28,6 +28,8 @@ export const signupRequestSchema = z.object({
     privacy: z.literal(true),
     marketing: z.boolean().default(false),
   }),
+  /** 비회원 장바구니 토큰 — 가입과 함께 회원 장바구니로 옮긴다 */
+  cartToken: z.string().optional(),
 });
 
 export type SignupRequest = z.infer<typeof signupRequestSchema>;
@@ -39,3 +41,16 @@ export const loginRequestSchema = z.object({
 });
 
 export type LoginRequest = z.infer<typeof loginRequestSchema>;
+
+/**
+ * 비회원 익명 세션 — `POST /auth/anonymous` 응답. `cartToken`을 `X-Cart-Token` 헤더로 보내면 장바구니와
+ * 비회원 주문이 이 세션에 쌓인다. 구매자 계정이 아니므로 `/me/*`에는 쓸 수 없다.
+ * 마지막 활동 후 30일이 지나거나 로그인·가입으로 회원 장바구니에 병합되면 더는 쓸 수 없다.
+ */
+export const anonymousSessionSchema = z.object({
+  cartToken: z.string(),
+  /** 이 시각까지 활동이 없으면 만료(ISO 8601). 쓸 때마다 늘어난다 */
+  expiresAt: z.string(),
+});
+
+export type AnonymousSession = z.infer<typeof anonymousSessionSchema>;