@sayren/storefront-sdk 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/storefront-sdk",
-  "version": "0.2.1",
+  "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/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>;