@sayren/storefront-sdk 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sayren/storefront-sdk",
+  "version": "0.1.0",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cochoio/shop.24.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "description": "sayren 스토어프론트 API SDK — zod 스키마 + fetch 클라이언트",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "biome check --write . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import { createHttp, path, type Query, resolveToken, type TokenSource } from "./http";
+import type { LoginRequest, SignupRequest } from "./schemas/auth";
+import { loginRequestSchema, signupRequestSchema, tokenPairSchema } from "./schemas/auth";
+import {
+  type AddCartItemRequest,
+  addCartItemRequestSchema,
+  cartSchema,
+  type UpdateCartItemRequest,
+  updateCartItemRequestSchema,
+} from "./schemas/cart";
+import {
+  categoryNodeSchema,
+  type ProductSearchParams,
+  productCardSchema,
+  productDetailSchema,
+  productFacetsSchema,
+} from "./schemas/catalog";
+import {
+  type CreateCheckoutRequest,
+  checkoutSessionSchema,
+  confirmPaymentRequestSchema,
+  confirmPaymentResultSchema,
+  createCheckoutRequestSchema,
+  paymentParamsSchema,
+  paymentStatusSchema,
+  type RequestPaymentRequest,
+  requestPaymentRequestSchema,
+} from "./schemas/checkout";
+import {
+  type CreateClaimRequest,
+  createClaimRequestSchema,
+  createClaimResultSchema,
+  myClaimSchema,
+} from "./schemas/claim";
+import {
+  type ClaimStatus,
+  type OrderItemStatus,
+  type PageParams,
+  pageSchema,
+} from "./schemas/common";
+import {
+  type CreateCustomerInquiryRequest,
+  type CustomerInquiryCategory,
+  createCustomerInquiryRequestSchema,
+  customerInquirySchema,
+} from "./schemas/customer-inquiry";
+import { type CreateInquiryRequest, publicInquirySchema } from "./schemas/inquiry";
+import {
+  type MemberAddressRequest,
+  memberAddressRequestSchema,
+  memberAddressSchema,
+  memberSchema,
+  type UpdateProfileRequest,
+  updateProfileRequestSchema,
+} from "./schemas/member";
+import { deliveryTrackingSchema, myOrderSchema } from "./schemas/order";
+import {
+  type CreateReviewRequest,
+  createReviewRequestSchema,
+  createReviewResultSchema,
+  publicReviewSchema,
+  reviewSummarySchema,
+  type UpdateReviewRequest,
+  updateReviewRequestSchema,
+  writableReviewSchema,
+} from "./schemas/review";
+import type { StorefrontSession } from "./session";
+
+export interface StorefrontClientOptions {
+  /** 예: https://demo.store.example.com/api/v1 */
+  baseUrl: string;
+  /**
+   * 테넌트 스토어 코드 — `X-Store-Code` 헤더로 전송한다. 공유 API 호스트로 접근할 때
+   * 서버가 Host 서브도메인을 추측하는 대신 명시적으로 테넌트를 지정한다(멀티테넌트 격리).
+   * 함수로 전달하면 매 요청마다 재평가.
+   */
+  storeCode?: TokenSource;
+  /** 회원 Access Token. 함수로 전달하면 매 요청마다 재평가 */
+  accessToken?: TokenSource;
+  /**
+   * accessToken의 별칭 옵션 — `{ auth: { accessToken } }` 형태로 전달할 수 있다.
+   * 우선순위: 명시적 `accessToken` 옵션 > `auth.accessToken` > `session.accessToken`.
+   */
+  auth?: { accessToken?: string };
+  /** 비회원 장바구니 토큰 */
+  cartToken?: TokenSource;
+  /** 서버가 새 X-Cart-Token을 발급했을 때 호출 */
+  onCartToken?: (token: string) => void;
+  /**
+   * SDK 세션 매니저 — 전달하면 accessToken(Bearer)·401 refresh·복구불가 시 clear를
+   * 자동 배선한다. `accessToken`/`auth.accessToken`을 명시하면 그쪽이 우선한다(하위호환).
+   */
+  session?: StorefrontSession;
+  fetch?: typeof globalThis.fetch;
+}
+
+const productPageSchema = pageSchema(productCardSchema).extend({
+  facets: productFacetsSchema.optional(),
+});
+
+const reviewPageSchema = pageSchema(publicReviewSchema).extend({
+  summary: reviewSummarySchema.optional(),
+});
+
+export function createStorefrontClient(options: StorefrontClientOptions) {
+  const { session } = options;
+
+  // 우선순위: 명시적 accessToken 옵션 > auth.accessToken 별칭 > session.accessToken.
+  // session만 전달되고 나머지가 없으면 그쪽에서 배선(하위호환 — 기존 옵션 조합은 그대로 동작).
+  const accessTokenSource: TokenSource =
+    options.accessToken ??
+    options.auth?.accessToken ??
+    (session ? () => session.accessToken : undefined);
+  const refresh = session ? () => session.refresh() : undefined;
+  const onUnauthorized = session ? () => session.clear() : undefined;
+
+  const http = createHttp({
+    baseUrl: options.baseUrl,
+    fetch: options.fetch,
+    headers: () => {
+      const headers: Record<string, string> = {};
+      const storeCode = resolveToken(options.storeCode);
+      if (storeCode) headers["x-store-code"] = storeCode;
+      const accessToken = resolveToken(accessTokenSource);
+      if (accessToken) headers.authorization = `Bearer ${accessToken}`;
+      const cartToken = resolveToken(options.cartToken);
+      if (cartToken) headers["x-cart-token"] = cartToken;
+      return headers;
+    },
+    onResponse: (response) => {
+      const issued = response.headers.get("x-cart-token");
+      if (issued) options.onCartToken?.(issued);
+    },
+    refresh,
+    onUnauthorized,
+  });
+
+  return {
+    /** 현재 세션 accessToken (session 미전달 시 null) */
+    get accessToken(): string | null {
+      return session ? session.accessToken : null;
+    },
+    /** 현재 세션 refreshToken (session 미전달 시 null) */
+    get refreshToken(): string | null {
+      return session ? session.refreshToken : null;
+    },
+    /** session.userinfo() 위임 — session 미전달 시 에러 */
+    userinfo() {
+      if (!session) throw new Error("세션 없음 — createStorefrontSession 필요");
+      return session.userinfo();
+    },
+    auth: {
+      signup: (body: SignupRequest) =>
+        http.request("POST", "/auth/signup", tokenPairSchema, {
+          body: signupRequestSchema.parse(body),
+        }),
+      login: (body: LoginRequest) =>
+        http.request("POST", "/auth/login", tokenPairSchema, {
+          body: loginRequestSchema.parse(body),
+        }),
+      refresh: (refreshToken: string) =>
+        http.request("POST", "/auth/token/refresh", tokenPairSchema, { body: { refreshToken } }),
+      logout: () => http.requestVoid("POST", "/auth/logout"),
+    },
+
+    catalog: {
+      listCategories: () => http.request("GET", "/categories", z.array(categoryNodeSchema)),
+      searchProducts: (params?: ProductSearchParams) =>
+        http.request("GET", "/products", productPageSchema, { query: params as Query }),
+      getProduct: (productId: string) =>
+        http.request("GET", path`/products/${productId}`, productDetailSchema),
+      listProductReviews: (
+        productId: string,
+        params?: PageParams & {
+          rating?: number;
+          hasImage?: boolean;
+          sort?: "latest" | "ratingDesc" | "ratingAsc" | "helpful";
+        },
+      ) =>
+        http.request("GET", path`/products/${productId}/reviews`, reviewPageSchema, {
+          query: params as Query,
+        }),
+      listProductInquiries: (productId: string, params?: PageParams) =>
+        http.request(
+          "GET",
+          path`/products/${productId}/inquiries`,
+          pageSchema(publicInquirySchema),
+          {
+            query: params as Query,
+          },
+        ),
+      createInquiry: (productId: string, body: CreateInquiryRequest) =>
+        http.requestVoid("POST", path`/products/${productId}/inquiries`, { body }),
+    },
+
+    cart: {
+      get: () => http.request("GET", "/cart", cartSchema),
+      addItem: (body: AddCartItemRequest) =>
+        http.request("POST", "/cart/items", cartSchema, {
+          body: addCartItemRequestSchema.parse(body),
+        }),
+      updateItem: (cartItemId: string, body: UpdateCartItemRequest) =>
+        http.request("PATCH", path`/cart/items/${cartItemId}`, cartSchema, {
+          body: updateCartItemRequestSchema.parse(body),
+        }),
+      removeItem: (cartItemId: string) =>
+        http.requestVoid("DELETE", path`/cart/items/${cartItemId}`),
+    },
+
+    checkout: {
+      create: (body: CreateCheckoutRequest) =>
+        http.request("POST", "/checkout", checkoutSessionSchema, {
+          body: createCheckoutRequestSchema.parse(body),
+        }),
+      /**
+       * 결제 시작 — 결제 세션을 만들고 결제 팝업 URL(`pgParams.popupUrl`)을 돌려준다.
+       * `pgProvider`는 첫 결제 시도의 PG다(현재 `tosspayments`·`portone`, 새 PG가 추가돼도 파싱은 깨지지 않는다).
+       *
+       * PG 관련 에러(`ApiError.code`) — 둘 다 "결제 수단 준비 중" 안내를 권장한다.
+       * - 409 `PAYMENT_NOT_CONFIGURED`: 스토어에 사용 중인 PG가 없다. 결제 세션을 만들지 않는다
+       * - 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 }),
+        }),
+    },
+
+    payments: {
+      /**
+       * `GET /storefront/v1/payments/{paymentId}` — 결제 상태 조회. 결제 팝업이 결과(postMessage)를 알리지 못하고 닫혔을 때
+       * 부모 창이 `expiresAt`까지 폴링해 결과를 확인한다. `completed`면 `orderId`로 완료 화면, `processing`이면 계속 폴링,
+       * `pending`이면 기존 안내, `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),
+    },
+
+    myOrders: {
+      list: (params?: PageParams & { status?: OrderItemStatus; from?: string }) =>
+        http.request("GET", "/me/orders", pageSchema(myOrderSchema), { query: params as Query }),
+      get: (orderId: string) => http.request("GET", path`/me/orders/${orderId}`, myOrderSchema),
+      getGuestOrder: (orderId: string, body: { phone: string; orderPassword: string }) =>
+        http.request("POST", path`/guest/orders/${orderId}`, myOrderSchema, { body }),
+      getDelivery: (orderItemId: string) =>
+        http.request("GET", path`/me/order-items/${orderItemId}/delivery`, deliveryTrackingSchema),
+      decidePurchase: (orderItemId: string) =>
+        http.requestVoid("POST", path`/me/order-items/${orderItemId}/purchase-decision`),
+    },
+
+    myClaims: {
+      create: (orderItemId: string, body: CreateClaimRequest) =>
+        http.request("POST", path`/me/order-items/${orderItemId}/claims`, createClaimResultSchema, {
+          body: createClaimRequestSchema.parse(body),
+        }),
+      list: (params?: PageParams & { status?: ClaimStatus }) =>
+        http.request("GET", "/me/claims", pageSchema(myClaimSchema), { query: params as Query }),
+      withdraw: (claimId: string) => http.requestVoid("POST", path`/me/claims/${claimId}/withdraw`),
+    },
+
+    member: {
+      me: () => http.request("GET", "/me", memberSchema),
+      updateMe: (body: UpdateProfileRequest) =>
+        http.requestVoid("PATCH", "/me", { body: updateProfileRequestSchema.parse(body) }),
+      listAddresses: () => http.request("GET", "/me/addresses", z.array(memberAddressSchema)),
+      createAddress: (body: MemberAddressRequest) =>
+        http.requestVoid("POST", "/me/addresses", { body: memberAddressRequestSchema.parse(body) }),
+      updateAddress: (addressId: string, body: MemberAddressRequest) =>
+        http.requestVoid("PUT", path`/me/addresses/${addressId}`, {
+          body: memberAddressRequestSchema.parse(body),
+        }),
+      deleteAddress: (addressId: string) =>
+        http.requestVoid("DELETE", path`/me/addresses/${addressId}`),
+      listWishlist: (params?: PageParams) =>
+        http.request("GET", "/me/wishlist", pageSchema(productCardSchema), {
+          query: params as Query,
+        }),
+      addWishlist: (productId: string) =>
+        http.requestVoid("POST", "/me/wishlist", { body: { productId } }),
+      removeWishlist: (productId: string) =>
+        http.requestVoid("DELETE", path`/me/wishlist/${productId}`),
+    },
+
+    reviews: {
+      listWritable: () =>
+        http.request("GET", "/me/reviews/writable", z.array(writableReviewSchema)),
+      create: (orderItemId: string, body: CreateReviewRequest) =>
+        http.request(
+          "POST",
+          path`/me/order-items/${orderItemId}/review`,
+          createReviewResultSchema,
+          {
+            body: createReviewRequestSchema.parse(body),
+          },
+        ),
+      update: (reviewId: string, body: UpdateReviewRequest) =>
+        http.requestVoid("PUT", path`/me/reviews/${reviewId}`, {
+          body: updateReviewRequestSchema.parse(body),
+        }),
+      remove: (reviewId: string) => http.requestVoid("DELETE", path`/me/reviews/${reviewId}`),
+    },
+
+    inquiries: {
+      listMine: (params?: PageParams & { answered?: boolean }) =>
+        http.request("GET", "/me/inquiries", pageSchema(publicInquirySchema), {
+          query: params as Query,
+        }),
+    },
+
+    me: {
+      customerInquiries: {
+        create: (body: CreateCustomerInquiryRequest) =>
+          http.request("POST", "/me/customer-inquiries", customerInquirySchema, {
+            body: createCustomerInquiryRequestSchema.parse(body),
+          }),
+        list: (params?: PageParams & { answered?: boolean; category?: CustomerInquiryCategory }) =>
+          http.request("GET", "/me/customer-inquiries", pageSchema(customerInquirySchema), {
+            query: params as Query,
+          }),
+        get: (inquiryId: string) =>
+          http.request("GET", path`/me/customer-inquiries/${inquiryId}`, customerInquirySchema),
+      },
+    },
+  };
+}
+
+export type StorefrontClient = ReturnType<typeof createStorefrontClient>;

package/src/http.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+
+/** 표준 엔벨로프의 $.error 상세 */
+export const errorDetailSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  traceId: z.string().optional(),
+  /**
+   * 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
+   * `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
+   */
+  details: z.record(z.string(), z.unknown()).optional().catch(undefined),
+});
+
+/** 표준 응답 엔벨로프 — $.meta / $.data / $.error */
+export const envelopeSchema = z.object({
+  meta: z.object({
+    status: z.number(),
+    code: z.string(),
+    message: z.string(),
+    isSuccess: z.boolean(),
+  }),
+  data: z.unknown().optional(),
+  /** 구형 필드 — data로 개명되기 전 응답과의 전환기 호환 */
+  content: z.unknown().optional(),
+  error: errorDetailSchema.nullable(),
+});
+
+export type ApiErrorBody = z.infer<typeof errorDetailSchema>;
+
+/** 표준 엔벨로프면 $.data(구형 $.content)를, 아니면(평면 응답) 본문 전체를 반환 */
+export function unwrapData(json: unknown): unknown {
+  const envelope = envelopeSchema.safeParse(json);
+  if (!envelope.success) return json;
+  return envelope.data.data ?? envelope.data.content ?? null;
+}
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    message: string,
+    public readonly traceId?: string,
+    public readonly body?: unknown,
+    /** 엔벨로프 `$.error.details` — 에러 코드별 보조 데이터. 없으면 undefined */
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/**
+ * 비-2xx 응답 본문(raw JSON)을 표준 ApiError로 변환한다 — http 클라이언트와 session 매니저가
+ * **동일한 에러 형태**(status·code·message·traceId)를 던지도록 하는 단일 원천.
+ * 표준 엔벨로프($.error) 우선, 구형 평면 에러({ code, message })는 폴백.
+ */
+export function toApiError(status: number, raw: unknown): ApiError {
+  const envelope = envelopeSchema.safeParse(raw);
+  const detail = envelope.success
+    ? envelope.data.error
+    : (errorDetailSchema.safeParse(raw).data ?? null);
+  if (detail) {
+    return new ApiError(status, detail.code, detail.message, detail.traceId, raw, detail.details);
+  }
+  return new ApiError(status, "UNKNOWN", `HTTP ${status}`, undefined, raw);
+}
+
+/**
+ * 경로 템플릿 태그 — 보간 값(경로 파라미터)마다 encodeURIComponent를 적용한다.
+ * `/`·`?`·`#` 등이 섞인 id가 다른 경로·쿼리로 해석되지 않게 한다. 예: path`/payments/${id}`
+ * (store-sdk `path`와 같은 구현)
+ */
+export function path(strings: TemplateStringsArray, ...params: Array<string | number>): string {
+  return strings.reduce(
+    (acc, part, i) => acc + part + (i < params.length ? encodeURIComponent(String(params[i])) : ""),
+    "",
+  );
+}
+
+export type TokenSource = string | null | undefined | (() => string | null | undefined);
+
+export function resolveToken(source: TokenSource): string | null {
+  const value = typeof source === "function" ? source() : source;
+  return value ?? null;
+}
+
+export interface HttpOptions {
+  baseUrl: string;
+  fetch?: typeof globalThis.fetch;
+  headers?: () => Record<string, string>;
+  onResponse?: (response: Response) => void;
+  /**
+   * 401 시 호출 — 세션을 갱신하고 true면 요청을 **1회 재시도**한다(headers 콜백이 새 토큰을 읽는다).
+   * false거나 재시도 후에도 401이면 onUnauthorized로 넘어간다.
+   */
+  refresh?: () => Promise<boolean>;
+  /** 복구 불가능한 401(갱신 실패/재시도 후에도 401) 시 호출 — 재로그인 유도용 */
+  onUnauthorized?: () => void;
+}
+
+export type Query = Record<string, string | number | boolean | undefined>;
+
+export function buildQuery(query?: Query): string {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+
+export interface RequestOptions {
+  query?: Query;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface Http {
+  request<T>(
+    method: string,
+    path: string,
+    schema: z.ZodType<T>,
+    options?: RequestOptions,
+  ): Promise<T>;
+  requestVoid(method: string, path: string, options?: RequestOptions): Promise<void>;
+}
+
+export function createHttp(options: HttpOptions): Http {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+
+  async function send(
+    method: string,
+    path: string,
+    request?: RequestOptions,
+    retried = false,
+  ): Promise<Response> {
+    const url = `${options.baseUrl}${path}${buildQuery(request?.query)}`;
+    const headers: Record<string, string> = {
+      ...(request?.body !== undefined ? { "content-type": "application/json" } : {}),
+      ...options.headers?.(),
+      ...request?.headers,
+    };
+    const response = await fetchFn(url, {
+      method,
+      headers,
+      body: request?.body !== undefined ? JSON.stringify(request.body) : undefined,
+    });
+    options.onResponse?.(response);
+    // 401 → 세션 갱신 후 1회 재시도. headers 콜백이 갱신된 토큰을 읽으므로 재시도는 새 토큰으로 나간다.
+    if (response.status === 401 && !retried && options.refresh) {
+      if (await options.refresh()) return send(method, path, request, true);
+    }
+    if (!response.ok) {
+      if (response.status === 401) options.onUnauthorized?.();
+      const raw = await response.json().catch(() => null);
+      throw toApiError(response.status, raw);
+    }
+    return response;
+  }
+
+  return {
+    async request<T>(
+      method: string,
+      path: string,
+      schema: z.ZodType<T>,
+      request?: RequestOptions,
+    ): Promise<T> {
+      const response = await send(method, path, request);
+      const json: unknown = await response.json();
+      return schema.parse(unwrapData(json));
+    },
+    async requestVoid(method: string, path: string, request?: RequestOptions): Promise<void> {
+      await send(method, path, request);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type { StorefrontClient, StorefrontClientOptions } from "./client";
+export { createStorefrontClient } from "./client";
+export type { Query, TokenSource } from "./http";
+export { ApiError, buildQuery } from "./http";
+export * from "./schemas/auth";
+export * from "./schemas/cart";
+export * from "./schemas/catalog";
+export * from "./schemas/checkout";
+export * from "./schemas/claim";
+export * from "./schemas/common";
+export * from "./schemas/customer-inquiry";
+export * from "./schemas/inquiry";
+export * from "./schemas/member";
+export * from "./schemas/order";
+export * from "./schemas/review";
+export {
+  createStorefrontSession,
+  type SessionStorage,
+  STOREFRONT_SESSION_KEYS,
+  type StorefrontSession,
+  type StorefrontSessionOptions,
+} from "./session";

package/src/schemas/auth.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+export const tokenPairSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  expiresIn: z.number().int(),
+});
+
+export type TokenPair = z.infer<typeof tokenPairSchema>;
+
+export const signupRequestSchema = z.object({
+  email: z.email(),
+  password: z
+    .string()
+    .min(10, "비밀번호는 10자 이상이어야 합니다")
+    .refine(
+      (value) =>
+        [/[a-zA-Z]/, /[0-9]/, /[^a-zA-Z0-9]/].filter((pattern) => pattern.test(value)).length >= 2,
+      "영문/숫자/특수문자 중 2종 이상을 조합해야 합니다",
+    ),
+  name: z.string().min(1).max(50),
+  phone: z
+    .string()
+    .regex(/^01[0-9]{8,9}$/, "휴대폰 번호 형식이 아닙니다 (예: 01012345678)")
+    .optional(),
+  agreements: z.object({
+    terms: z.literal(true),
+    privacy: z.literal(true),
+    marketing: z.boolean().default(false),
+  }),
+});
+
+export type SignupRequest = z.infer<typeof signupRequestSchema>;
+
+export const loginRequestSchema = z.object({
+  email: z.email(),
+  password: z.string().min(1),
+  cartToken: z.string().optional(),
+});
+
+export type LoginRequest = z.infer<typeof loginRequestSchema>;

package/src/schemas/cart.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+export const cartItemSchema = z.object({
+  cartItemId: z.string(),
+  productId: z.string(),
+  productName: z.string(),
+  thumbnailUrl: z.url(),
+  optionId: z.string().nullable(),
+  optionName: z.string().nullable(),
+  quantity: z.number().int(),
+  unitPrice: z.number().int(),
+  totalPrice: z.number().int(),
+  purchasable: z.boolean(),
+  unpurchasableReason: z.enum(["SOLD_OUT", "SUSPENDED", "CLOSED"]).nullable(),
+});
+
+export type CartItem = z.infer<typeof cartItemSchema>;
+
+export const cartSchema = z.object({
+  items: z.array(cartItemSchema),
+  summary: z.object({
+    productAmount: z.number().int(),
+    deliveryFee: z.number().int(),
+    totalAmount: z.number().int(),
+  }),
+});
+
+export type Cart = z.infer<typeof cartSchema>;
+
+export const addCartItemRequestSchema = z.object({
+  productId: z.string(),
+  optionId: z.string().optional(),
+  quantity: z.number().int().min(1).max(999),
+});
+
+export type AddCartItemRequest = z.infer<typeof addCartItemRequestSchema>;
+
+export const updateCartItemRequestSchema = z
+  .object({
+    quantity: z.number().int().min(1).max(999).optional(),
+    optionId: z.string().optional(),
+  })
+  .refine((value) => Object.values(value).some((v) => v !== undefined), {
+    message: "최소 1개 필드가 필요합니다",
+  });
+
+export type UpdateCartItemRequest = z.infer<typeof updateCartItemRequestSchema>;