@sayren/store-sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,877 @@
+import { z } from "zod";
+import { base64Utf8 } from "./base64";
+import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
+import {
+  type ApiClientListParams,
+  apiClientSchema,
+  apiClientSecretRotatedSchema,
+  type OAuthClientRegistrationRequest,
+  oauthClientRegistrationRequestSchema,
+  oauthClientRegistrationResponseSchema,
+} from "./schemas/api-client";
+import { type ApiLogListOptions, apiLogPageSchema, apiLogSummarySchema } from "./schemas/api-log";
+import {
+  type ApiTokenCreateRequest,
+  apiTokenCreatedSchema,
+  apiTokenCreateRequestSchema,
+  apiTokenSchema,
+  clientCredentialsTokenResponseSchema,
+  myAccountSchema,
+  myStoreSchema,
+} from "./schemas/auth";
+import {
+  type CategoryCreateRequest,
+  type CategoryDeleteStrategy,
+  type CategoryPatchRequest,
+  categoryAttributeSchema,
+  categoryCreateRequestSchema,
+  categoryPatchRequestSchema,
+  categorySchema,
+  categorySearchResultSchema,
+  categoryTreeNodeSchema,
+  categoryWithPathSchema,
+} from "./schemas/category";
+import {
+  approveClaimResultSchema,
+  type ClaimListParams,
+  claimSchema,
+  claimStatusSchema,
+  type RejectClaimRequest,
+  rejectClaimRequestSchema,
+} from "./schemas/claim";
+import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
+import {
+  type CustomerInquiryCategory,
+  inquirySchema,
+  type ReviewListParams,
+  reviewSchema,
+  type SettlementListParams,
+  sellerCustomerInquirySchema,
+  settlementDetailSchema,
+  settlementSummarySchema,
+  type WebhookDeliveryListParams,
+  type WebhookRequest,
+  type WebhookTestRequest,
+  webhookCreatedSchema,
+  webhookDeliverySchema,
+  webhookRedeliverFailedResultSchema,
+  webhookRequestSchema,
+  webhookSchema,
+  webhookSecretRotatedSchema,
+  webhookTestRequestSchema,
+  webhookTestResultSchema,
+} from "./schemas/misc";
+import {
+  type CancelBySellerRequest,
+  cancelBySellerRequestSchema,
+  carrierSchema,
+  type DispatchRequest,
+  deliveryInfoSchema,
+  dispatchRequestSchema,
+  type HoldOrderItemRequest,
+  holdOrderItemRequestSchema,
+  type OrderItemListParams,
+  type OrderListParams,
+  orderItemSchema,
+  orderSchema,
+  orderSummarySchema,
+} from "./schemas/order";
+import {
+  type PaymentListParams,
+  type PgEnvironment,
+  type PgProvider,
+  paymentProviderSchema,
+  paymentProviderVerificationSchema,
+  paymentRecordDetailSchema,
+  paymentRecordPageSchema,
+  paymentSettingsSchema,
+  pgEnvironmentSchema,
+  pgProviderSchema,
+  type SalesReportParams,
+  salesReportQuerySchema,
+  salesReportSchema,
+  type UpdatePaymentProviderRequest,
+  type UpdatePaymentSettingsRequest,
+  type UpsertPortOneProviderRequest,
+  type UpsertTossPaymentsProviderRequest,
+  updatePaymentProviderRequestSchema,
+  updatePaymentSettingsRequestSchema,
+  upsertPortOneProviderRequestSchema,
+  upsertTossPaymentsProviderRequestSchema,
+  type VerifyPaymentProviderRequest,
+  verifyPaymentProviderRequestSchema,
+} from "./schemas/payment";
+import {
+  type DiscountRequest,
+  discountRequestSchema,
+  discountSchema,
+  type OptionModelRequest,
+  optionModelRequestSchema,
+  optionModelSchema,
+  type ProductCreateRequest,
+  type ProductListParams,
+  type ProductPatchRequest,
+  type ProductStatus,
+  productCreateRequestSchema,
+  productPatchRequestSchema,
+  productSchema,
+  productStatusSchema,
+  productSummarySchema,
+  type VariantStockRequest,
+  variantStockRequestSchema,
+  variantStockSchema,
+} from "./schemas/product";
+import {
+  type AddressType,
+  invitationSchema,
+  type SellerAddressRequest,
+  sellerAddressRequestSchema,
+  sellerAddressSchema,
+  storeMemberSchema,
+  storeSchema,
+} from "./schemas/store";
+import { type UploadRequest, uploadRequestSchema, uploadTicketSchema } from "./schemas/upload";
+import type { AuthorizeOptions, StoreSession } from "./session";
+
+export interface StoreClientOptions {
+  /** 예: https://api.example.com/v1 */
+  baseUrl: string;
+  /** 유저 토큰 (1단계). 인증/스토어 목록 API에 사용 */
+  userToken?: TokenSource;
+  /** 스토어 토큰 (3단계). 테넌트 리소스 API에 사용 */
+  storeToken?: TokenSource;
+  /** 테넌트 storeId — storeHttp(테넌트 리소스) 요청에 X-Store-Id로 실린다(userToken 직접 인가). */
+  storeId?: TokenSource;
+  /**
+   * 토큰 주입 모드 — PAT/storeToken급(테넌트 바인딩, role 없음)을 storeHttp Bearer로 싣는다.
+   * userToken이 아니다(비인터랙티브 M2M/CLI 경로용). storeToken과 함께 주면 storeToken이 우선한다.
+   */
+  auth?: { apiToken?: string };
+  /**
+   * SDK 세션 매니저 — 전달하면 userToken(Bearer)·401 refresh·복구불가 시 clear를
+   * 이 세션에서 자동 배선한다. 개별 옵션(userToken/refresh/onUnauthorized)을 명시하면 그쪽이 우선한다.
+   */
+  session?: StoreSession;
+  /** 401 시 세션 갱신 시도 — true면 요청을 1회 재시도한다(refresh 토큰 회전) */
+  refresh?: () => Promise<boolean>;
+  /** 복구 불가능한 401(갱신 실패/재시도 후에도 401) 시 호출 — 재로그인 유도용 */
+  onUnauthorized?: () => void;
+  fetch?: typeof globalThis.fetch;
+}
+
+function formBody(fields: Record<string, string>): string {
+  return new URLSearchParams(fields).toString();
+}
+
+export function createStoreClient(options: StoreClientOptions) {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const { session } = options;
+
+  // session이 있으면 userToken/refresh/onUnauthorized의 기본값을 세션에서 배선한다.
+  // 개별 옵션을 명시하면 그쪽이 우선(하위호환) — session 미전달 시 기존 동작 그대로.
+  const userTokenSource: TokenSource =
+    options.userToken ?? (session ? () => session.getToken() : undefined);
+  const refresh = options.refresh ?? (session ? () => session.refresh() : undefined);
+  const onUnauthorized = options.onUnauthorized ?? (session ? () => session.clear() : undefined);
+  // storeToken(명시 옵션)이 auth.apiToken(PAT/storeToken급 주입)보다 우선한다.
+  const storeTokenSource: TokenSource = options.storeToken ?? options.auth?.apiToken;
+
+  const userHttp = createHttp({
+    baseUrl: options.baseUrl,
+    fetch: fetchFn,
+    headers: () => {
+      const token = resolveToken(userTokenSource);
+      return token ? { authorization: `Bearer ${token}` } : ({} as Record<string, string>);
+    },
+    refresh,
+    onUnauthorized,
+  });
+
+  const storeHttp = createHttp({
+    baseUrl: options.baseUrl,
+    fetch: fetchFn,
+    headers: () => {
+      const token = resolveToken(storeTokenSource);
+      const storeId = resolveToken(options.storeId);
+      return {
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+        ...(storeId ? { "x-store-id": storeId } : {}),
+      };
+    },
+    refresh,
+    onUnauthorized,
+  });
+
+  /** `PATCH /v1/store/payment-providers/{provider}` 단일 구현 — `updateProvider`·`setSandboxMode`가 공유한다 */
+  function updatePaymentProvider(provider: PgProvider, body: UpdatePaymentProviderRequest) {
+    return storeHttp.request(
+      "PATCH",
+      path`/store/payment-providers/${pgProviderSchema.parse(provider)}`,
+      paymentProviderSchema,
+      { body: updatePaymentProviderRequestSchema.parse(body) },
+    );
+  }
+
+  function idempotency(key?: string): Record<string, string> | undefined {
+    return key ? { "idempotency-key": key } : undefined;
+  }
+
+  function requireSession(): StoreSession {
+    if (!session) throw new Error("oauth 세션 없음 — createStoreSession 필요");
+    return session;
+  }
+
+  return {
+    /** session의 현재 userToken (session 미배선 시 null — 던지지 않음) */
+    get accessToken(): string | null {
+      return session ? session.accessToken : null;
+    },
+    /** session의 현재 refresh 토큰 (session 미배선 시 null — 던지지 않음) */
+    get refreshToken(): string | null {
+      return session ? session.refreshToken : null;
+    },
+    /** session.authorize 패스스루 — session 미배선 시 명확한 에러를 던진다 */
+    authorize: (authorizeOptions: AuthorizeOptions) => requireSession().authorize(authorizeOptions),
+    /** session.userinfo 패스스루 — session 미배선 시 명확한 에러를 던진다 */
+    userinfo: () => requireSession().userinfo(),
+
+    auth: {
+      /**
+       * 서버 간 연동(M2M) — client_credentials grant (client_secret_basic).
+       * 클라이언트가 스토어에 바인딩되어 있어 **storeToken이 곧바로 발급**된다.
+       * ⚠ client_secret은 서버 환경에서만 사용할 것 (브라우저 반입 금지)
+       */
+      async issueStoreTokenByClientCredentials(
+        clientId: string,
+        clientSecret: string,
+        scope?: string,
+      ) {
+        // RFC 7617 client_secret_basic — UTF-8 바이트를 base64로 인코딩한다.
+        const credentials = base64Utf8(`${clientId}:${clientSecret}`);
+        const response = await fetchFn(`${options.baseUrl}/oauth2/token`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            authorization: `Basic ${credentials}`,
+          },
+          body: formBody({ grant_type: "client_credentials", ...(scope ? { scope } : {}) }),
+        });
+        if (!response.ok) {
+          const body = (await response.json().catch(() => null)) as {
+            error_description?: string;
+          } | null;
+          throw new Error(body?.error_description ?? `토큰 발급 실패 (HTTP ${response.status})`);
+        }
+        return clientCredentialsTokenResponseSchema.parse(unwrapData(await response.json()));
+      },
+      /** 2단계 — 소속 스토어 목록 */
+      listMyStores: () => userHttp.request("GET", "/me/stores", z.array(myStoreSchema)),
+      /** RFC 7009 — token을 폐기한다 (public client는 client_id만 동반) */
+      async revoke(token: string, clientId: string) {
+        await fetchFn(`${options.baseUrl}/oauth2/revoke`, {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+          body: formBody({ token, client_id: clientId }),
+        });
+      },
+      me: () => userHttp.request("GET", "/me", myAccountSchema),
+    },
+
+    /** API 토큰(PAT) 관리 — OWNER/ADMIN 전용. 발급된 토큰은 storeToken처럼 Bearer로 사용 */
+    apiTokens: {
+      create: (body: ApiTokenCreateRequest) =>
+        storeHttp.request("POST", "/store/api-tokens", apiTokenCreatedSchema, {
+          body: apiTokenCreateRequestSchema.parse(body),
+        }),
+      list: () => storeHttp.request("GET", "/store/api-tokens", z.array(apiTokenSchema)),
+      revoke: (tokenId: string) =>
+        storeHttp.requestVoid("DELETE", path`/store/api-tokens/${tokenId}`),
+    },
+
+    /**
+     * 앱(OAuth 클라이언트) 관리 — OWNER/ADMIN storeToken 전용(PAT·M2M 거부). auth-spec §12, 부록 B-13.
+     * 시크릿 평문은 register·rotateSecret 응답에서만 한 번 노출된다(apiTokens.create와 같은 성격).
+     */
+    apiClients: {
+      /**
+       * DCR 등록 (RFC 7591) — `POST /v1/oauth2/register`. OAuth 프로토콜 표면이라 응답이 평면 JSON이다.
+       * 등록 오류(`invalid_client_metadata`·`invalid_redirect_uri`)는 ApiError(code=error,
+       * message=error_description)로, Bearer 인증 오류는 엔벨로프 그대로 ApiError로 던진다.
+       */
+      register: (body: OAuthClientRegistrationRequest) =>
+        storeHttp.request("POST", "/oauth2/register", oauthClientRegistrationResponseSchema, {
+          body: oauthClientRegistrationRequestSchema.parse(body),
+        }),
+      list: (params?: ApiClientListParams) =>
+        storeHttp.request("GET", "/store/api-clients", z.array(apiClientSchema), {
+          query: params as Query,
+        }),
+      get: (clientId: string) =>
+        storeHttp.request("GET", path`/store/api-clients/${clientId}`, apiClientSchema),
+      /** confidential 전용. 기존 시크릿은 즉시 무효(유예 없음) */
+      rotateSecret: (clientId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/store/api-clients/${clientId}/rotate-secret`,
+          apiClientSecretRotatedSchema,
+        ),
+      /** REVOKED로 전환(되돌릴 수 없음). 이미 비활성이면 현재 상태를 그대로 돌려준다 */
+      deactivate: (clientId: string) =>
+        storeHttp.request("POST", path`/store/api-clients/${clientId}/deactivate`, apiClientSchema),
+    },
+
+    /**
+     * 미디어 업로드 — 자리를 받아(`POST /uploads`) 파일 바이트는 호출자가
+     * `uploadUrl`로 직접 PUT한다. 업로드가 끝나면 `url`이 공개 주소가 된다.
+     */
+    uploads: {
+      create: (body: UploadRequest) =>
+        storeHttp.request("POST", "/uploads", uploadTicketSchema, {
+          body: uploadRequestSchema.parse(body),
+        }),
+    },
+
+    products: {
+      list: (params?: ProductListParams) =>
+        storeHttp.request("GET", "/products", pageSchema(productSummarySchema), {
+          query: params as Query,
+        }),
+      get: (productId: string) =>
+        storeHttp.request("GET", path`/products/${productId}`, productSchema),
+      create: (body: ProductCreateRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/products", productSchema, {
+          body: productCreateRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      update: (productId: string, body: ProductCreateRequest) =>
+        storeHttp.request("PUT", path`/products/${productId}`, productSchema, {
+          body: productCreateRequestSchema.parse(body),
+        }),
+      patch: (productId: string, body: ProductPatchRequest) =>
+        storeHttp.requestVoid("PATCH", path`/products/${productId}`, {
+          body: productPatchRequestSchema.parse(body),
+        }),
+      remove: (productId: string) => storeHttp.requestVoid("DELETE", path`/products/${productId}`),
+      bulkUpdateStatus: (productIds: string[], status: ProductStatus, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/products/bulk/status", bulkResultSchema, {
+          body: { productIds, status: productStatusSchema.parse(status) },
+          headers: idempotency(idempotencyKey),
+        }),
+      /** 옵션 축(그룹) × 값 → variant 모델 조회 */
+      getOptionModel: (productId: string) =>
+        storeHttp.request("GET", path`/products/${productId}/options`, optionModelSchema),
+      /**
+       * 옵션 모델 전체 교체 — variants는 valueNames로 축 값을 지목한다.
+       * 응답으로 서버가 배정한 groupId·valueId·신규 variantId가 실린 교체 결과를 돌려준다.
+       */
+      replaceOptionModel: (productId: string, body: OptionModelRequest) =>
+        storeHttp.request("PUT", path`/products/${productId}/options`, optionModelSchema, {
+          body: optionModelRequestSchema.parse(body),
+        }),
+      /** 재고 변경 — stockQuantity(절대값) 또는 adjustment(증감) 하나만 전달한다 */
+      updateVariantStock: (productId: string, variantId: string, body: VariantStockRequest) =>
+        storeHttp.request(
+          "PATCH",
+          path`/products/${productId}/variants/${variantId}/stock`,
+          variantStockSchema,
+          { body: variantStockRequestSchema.parse(body) },
+        ),
+      getDiscount: (productId: string) =>
+        storeHttp.request("GET", path`/products/${productId}/discount`, discountSchema),
+      setDiscount: (productId: string, body: DiscountRequest) =>
+        storeHttp.request("PUT", path`/products/${productId}/discount`, discountSchema, {
+          body: discountRequestSchema.parse(body),
+        }),
+      removeDiscount: (productId: string) =>
+        storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
+    },
+
+    categories: {
+      list: (params?: { parentId?: string; flat?: boolean }) =>
+        storeHttp.request("GET", "/categories", z.array(categorySchema), {
+          query: params as Query,
+        }),
+      tree: () =>
+        storeHttp.request("GET", "/categories", z.array(categoryTreeNodeSchema), {
+          query: { tree: true } as Query,
+        }),
+      search: (q: string) =>
+        storeHttp.request("GET", "/categories", z.array(categorySearchResultSchema), {
+          query: { q } as Query,
+        }),
+      get: (categoryId: string) =>
+        storeHttp.request("GET", path`/categories/${categoryId}`, categoryWithPathSchema),
+      listAttributes: (categoryId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/categories/${categoryId}/attributes`,
+          z.array(categoryAttributeSchema),
+        ),
+      create: (body: CategoryCreateRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/categories", categorySchema, {
+          body: categoryCreateRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      update: (categoryId: string, body: CategoryPatchRequest) =>
+        storeHttp.request("PATCH", path`/categories/${categoryId}`, categorySchema, {
+          body: categoryPatchRequestSchema.parse(body),
+        }),
+      remove: (categoryId: string, opts?: { strategy?: CategoryDeleteStrategy }) =>
+        storeHttp.requestVoid("DELETE", path`/categories/${categoryId}`, {
+          query: (opts?.strategy ? { strategy: opts.strategy } : {}) as Query,
+        }),
+    },
+
+    orders: {
+      /**
+       * `GET /v1/orders`. `testPayment: "true"`는 테스트 결제(샌드박스) 주문만, `"false"`는 실결제 주문만, 생략하면 전부다.
+       * 그 밖의 값은 400 `INVALID_PARAMETER`. 행마다 `testPayment`가 붙는다.
+       */
+      list: (params: OrderListParams) =>
+        storeHttp.request("GET", "/orders", pageSchema(orderSummarySchema), {
+          query: params as unknown as Query,
+        }),
+      get: (orderId: string) => storeHttp.request("GET", path`/orders/${orderId}`, orderSchema),
+    },
+
+    orderItems: {
+      /** `GET /v1/order-items`. `testPayment` 필터는 `orders.list`와 같다 */
+      listChanged: (params: OrderItemListParams) =>
+        storeHttp.request("GET", "/order-items", pageSchema(orderItemSchema), {
+          query: params as unknown as Query,
+        }),
+      confirm: (orderItemId: string, idempotencyKey?: string) =>
+        storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/confirm`, {
+          headers: idempotency(idempotencyKey),
+        }),
+      confirmBulk: (orderItemIds: string[], idempotencyKey?: string) =>
+        storeHttp.request("POST", "/order-items/confirm", bulkResultSchema, {
+          body: { orderItemIds },
+          headers: idempotency(idempotencyKey),
+        }),
+      hold: (orderItemId: string, body: HoldOrderItemRequest) =>
+        storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/hold`, {
+          body: holdOrderItemRequestSchema.parse(body),
+        }),
+      releaseHold: (orderItemId: string) =>
+        storeHttp.requestVoid("DELETE", path`/order-items/${orderItemId}/hold`),
+      cancelBySeller: (orderItemId: string, body: CancelBySellerRequest, idempotencyKey?: string) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/cancel`,
+          z.object({
+            orderItemId: z.string(),
+            refundAmount: z.number().int(),
+            refundedAt: z.string(),
+          }),
+          { body: cancelBySellerRequestSchema.parse(body), headers: idempotency(idempotencyKey) },
+        ),
+      updateMemo: (orderItemId: string, memo: string) =>
+        storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/memo`, { body: { memo } }),
+      requestPurchaseDecision: (orderItemId: string) =>
+        storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/purchase-decision/request`),
+      extendPurchaseDecision: (orderItemId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/purchase-decision/extend`,
+          z.object({
+            orderItemId: z.string(),
+            autoDecisionDate: z.string(),
+            extendCount: z.number().int().max(2),
+          }),
+        ),
+      dispatch: (orderItemId: string, body: DispatchRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/order-items/${orderItemId}/dispatch`, deliveryInfoSchema, {
+          body: dispatchRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      dispatchBulk: (
+        dispatches: Array<{ orderItemId: string } & DispatchRequest>,
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request("POST", "/order-items/dispatch", bulkResultSchema, {
+          body: { dispatches },
+          headers: idempotency(idempotencyKey),
+        }),
+      updateTracking: (orderItemId: string, carrierCode: string, trackingNumber: string) =>
+        storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/dispatch/tracking`, {
+          body: { carrierCode, trackingNumber },
+        }),
+      getDelivery: (orderItemId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/order-items/${orderItemId}/delivery`,
+          deliveryInfoSchema.extend({
+            trackingEvents: z
+              .array(z.object({ status: z.string(), location: z.string(), occurredAt: z.string() }))
+              .optional(),
+          }),
+        ),
+    },
+
+    carriers: {
+      list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)),
+    },
+
+    claims: {
+      list: (params?: ClaimListParams) =>
+        storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params as Query }),
+      get: (claimId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/claims/${claimId}`,
+          claimSchema.extend({
+            histories: z
+              .array(
+                z.object({
+                  status: claimStatusSchema,
+                  actor: z.enum(["BUYER", "SELLER", "SYSTEM"]),
+                  occurredAt: z.string(),
+                }),
+              )
+              .optional(),
+          }),
+        ),
+      approve: (claimId: string, deductAmount?: number, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
+          body: deductAmount !== undefined ? { deductAmount } : {},
+          headers: idempotency(idempotencyKey),
+        }),
+      reject: (claimId: string, body: RejectClaimRequest) =>
+        storeHttp.requestVoid("POST", path`/claims/${claimId}/reject`, {
+          body: rejectClaimRequestSchema.parse(body),
+        }),
+      registerCollect: (
+        claimId: string,
+        body: { collectMethod: "SELLER_PICKUP" | "BUYER_SEND"; carrierCode?: string },
+      ) => storeHttp.requestVoid("POST", path`/claims/${claimId}/collect`, { body }),
+      completeCollect: (claimId: string) =>
+        storeHttp.requestVoid("POST", path`/claims/${claimId}/collect/complete`),
+      registerRedelivery: (claimId: string, carrierCode: string, trackingNumber: string) =>
+        storeHttp.requestVoid("POST", path`/claims/${claimId}/redelivery`, {
+          body: { carrierCode, trackingNumber },
+        }),
+      hold: (claimId: string, reason: string) =>
+        storeHttp.request(
+          "POST",
+          path`/claims/${claimId}/hold`,
+          z.object({ claimId: z.string(), holdExpiresAt: z.string() }),
+          { body: { reason } },
+        ),
+      releaseHold: (claimId: string) =>
+        storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
+    },
+
+    inquiries: {
+      list: (params?: PageParams & { answered?: boolean; productId?: string; from?: string }) =>
+        storeHttp.request("GET", "/inquiries", pageSchema(inquirySchema), {
+          query: params as Query,
+        }),
+      get: (inquiryId: string) =>
+        storeHttp.request("GET", path`/inquiries/${inquiryId}`, inquirySchema),
+      answer: (inquiryId: string, content: string) =>
+        storeHttp.requestVoid("POST", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
+      updateAnswer: (inquiryId: string, content: string) =>
+        storeHttp.requestVoid("PUT", path`/inquiries/${inquiryId}/answer`, { body: { content } }),
+    },
+
+    customerInquiries: {
+      list: (
+        params?: PageParams & {
+          answered?: boolean;
+          category?: CustomerInquiryCategory;
+          from?: string;
+        },
+      ) =>
+        storeHttp.request("GET", "/customer-inquiries", pageSchema(sellerCustomerInquirySchema), {
+          query: params as Query,
+        }),
+      get: (inquiryId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/customer-inquiries/${inquiryId}`,
+          sellerCustomerInquirySchema,
+        ),
+      answer: (inquiryId: string, content: string) =>
+        storeHttp.requestVoid("POST", path`/customer-inquiries/${inquiryId}/answer`, {
+          body: { content },
+        }),
+      updateAnswer: (inquiryId: string, content: string) =>
+        storeHttp.requestVoid("PUT", path`/customer-inquiries/${inquiryId}/answer`, {
+          body: { content },
+        }),
+    },
+
+    /**
+     * @deprecated 정산 API는 폐기 예정이다. 새 정산 레코드는 더 이상 만들어지지 않고 기존 레코드 조회만
+     * 유지된다(서버 응답 헤더 `Deprecation: true`). 대체는 {@link salesReport}(`GET /v1/sales-report`)다.
+     */
+    settlements: {
+      /** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
+      list: (params: SettlementListParams) =>
+        storeHttp.request("GET", "/settlements", pageSchema(settlementSummarySchema), {
+          query: params as unknown as Query,
+        }),
+      /** @deprecated `salesReport.get`을 쓴다. 기존 정산 레코드 조회만 유지된다 */
+      get: (settlementId: string, params?: PageParams) =>
+        storeHttp.request(
+          "GET",
+          path`/settlements/${settlementId}`,
+          settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() }),
+          { query: params as Query },
+        ),
+    },
+
+    /**
+     * 매출 리포트 (정산 API 대체) — 스코프 `settlement:r`. PG 승인 시각 기준 결제, PG 취소 완료 시각 기준
+     * 환불을 Asia/Seoul 날짜로 집계한다. `rows`는 활동 없는 날짜·PG·결제수단을 생략하므로 차트는 빈 구간을 0으로 채운다.
+     */
+    salesReport: {
+      /**
+       * `GET /v1/sales-report`. from·to는 양끝 포함, 최대 92일. 테스트 결제(샌드박스)의 승인·환불은 기본 제외이고
+       * `includeTest: "true"`면 포함한다(응답 `includeTest`에 적용 값). 400 `VALIDATION_FAILED`(형식),
+       * 400 `INVALID_PARAMETER`(없는 날짜·to<from), 400 `RANGE_TOO_WIDE`(기간 초과)
+       */
+      get: (params: SalesReportParams) =>
+        storeHttp.request("GET", "/sales-report", salesReportSchema, {
+          query: salesReportQuerySchema.parse(params),
+        }),
+    },
+
+    /**
+     * 결제 내역 — 스코프 `settlement:r`. 결제 건(세션) 단위이고 주문 목록과 다르다. 주문이 만들어지지 않은
+     * 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 그대로 나온다.
+     */
+    payments: {
+      /**
+       * `GET /v1/payments`. 기간 기준은 결제 시작 시각, 최대 92일이고 생략하면 최근 30일이다. 테스트 결제는
+       * `includeTest: true`일 때만 포함한다. 400 `INVALID_PARAMETER`(시각 형식·to<from), 400 `RANGE_TOO_WIDE`
+       */
+      list: (params: PaymentListParams = {}) =>
+        storeHttp.request("GET", "/payments", paymentRecordPageSchema, {
+          query: params as unknown as Query,
+        }),
+      /** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
+      get: (paymentId: string) =>
+        storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema),
+    },
+
+    /**
+     * 결제(PG) 설정 — **콘솔 OWNER 전용**. ADMIN·STAFF·PAT·M2M·3rd-party 앱 토큰은 스코프가 있어도
+     * 403 `INSUFFICIENT_ROLE`이다(조회 포함). OWNER 여부는 요청 시점의 스토어 멤버십으로 다시 확인하므로
+     * 양도·강등 직후의 옛 storeToken도 403이다(토큰을 재발급받는다). 비밀 값(시크릿 키·API Secret·웹훅 시크릿)은 요청으로만 보내고
+     * 응답에는 `secrets[].masked`(앞 4자리 마스킹)만 나온다.
+     */
+    paymentSettings: {
+      /** `GET /v1/store/payment-settings` — 라우팅 모드와 지원 PG 전부(연결된 것은 우선순위순) */
+      get: () => storeHttp.request("GET", "/store/payment-settings", paymentSettingsSchema),
+      /**
+       * `PUT /v1/store/payment-settings` — `priority`에는 연결된 PG를 개수와 무관하게 모두 한 번씩 나열한다
+       * (빠지거나 중복되면 400 `INVALID_PRIORITY`). 진행 중인 결제에는 적용되지 않는다.
+       */
+      update: (body: UpdatePaymentSettingsRequest) =>
+        storeHttp.request("PUT", "/store/payment-settings", paymentSettingsSchema, {
+          body: updatePaymentSettingsRequestSchema.parse(body),
+        }),
+      /**
+       * `PUT /v1/store/payment-providers/tosspayments` — 자격 증명 세트 저장. `environment`는 **저장할 세트**(`TEST`·`LIVE`)이고
+       * 결제에 쓰는 세트는 샌드박스 스위치(`setSandboxMode`)가 정한다. 처음 연결하면 `enabled: false`·`sandboxMode: true`로 만들어진다.
+       * 같은 가맹점(`clientKey`)이면 그 세트를 갱신하고, 가맹점이 바뀌면 새 세트를 만들고 이전 세트는 보관한다
+       * (`retiredCredentialCount` +1, 이미 받은 결제의 환불·대사에 계속 쓰인다). `secretKey`·`webhookSecret`을 생략하면
+       * 현재 세트의 값을 이어받고 `webhookSecret: null`은 삭제다. 저장하면 그 세트의 `lastVerification`이 초기화된다.
+       *
+       * 에러: 400 `PAYMENT_PROVIDER_INCOMPLETE`(시크릿 키 없음) · 400 `INVALID_CREDENTIALS`(형식·환경 불일치) ·
+       * 409 `PAYMENT_PROVIDER_VERIFICATION_FAILED`(라이브 사용 중인 PG의 LIVE 세트 가맹점을 바꾸려는데 저장 전 연결 테스트 실패.
+       * 저장되지 않는다. 같은 가맹점의 비밀 값 교체는 검사하지 않는다)
+       */
+      upsertTossPayments: (body: UpsertTossPaymentsProviderRequest) =>
+        storeHttp.request("PUT", "/store/payment-providers/tosspayments", paymentProviderSchema, {
+          body: upsertTossPaymentsProviderRequestSchema.parse(body),
+        }),
+      /**
+       * `PUT /v1/store/payment-providers/portone` — 자격 증명 세트 저장. 규칙·에러는 `upsertTossPayments`와 같다
+       * (가맹점 식별자는 `storeId`, 비밀 필드는 `apiSecret`·`webhookSecret`). 400 `INVALID_CREDENTIALS`에는 채널 키 중복이 포함된다.
+       */
+      upsertPortOne: (body: UpsertPortOneProviderRequest) =>
+        storeHttp.request("PUT", "/store/payment-providers/portone", paymentProviderSchema, {
+          body: upsertPortOneProviderRequestSchema.parse(body),
+        }),
+      /**
+       * `PATCH /v1/store/payment-providers/{provider}` — 사용 여부(`enabled`)·샌드박스 스위치(`sandboxMode`) 변경.
+       * 하나 이상 보내야 한다(아니면 요청 전에 ZodError). 검증을 모두 통과해야 한 번에 적용된다(부분 적용 없음).
+       * 끈 PG로 승인된 결제의 환불은 계속 그 PG로 간다.
+       *
+       * 에러
+       * - 404 `PAYMENT_PROVIDER_NOT_FOUND`: 연결되지 않은 PG
+       * - 409 `PAYMENT_PROVIDER_INCOMPLETE`: 켜려는데 활성 환경(샌드박스면 TEST, 아니면 LIVE) 세트가 없거나 불완전
+       * - 409 `LIVE_GATE_NOT_MET`: `sandboxMode: false`(라이브 전환)인데 개방 조건 미충족. `ApiError.details`가
+       *   `{ conditions: LiveGateCondition[] }`(조건별 `met`)이다. `liveGateErrorDetailsSchema`로 파싱한다
+       * - 409 `LIVE_PAYMENTS_DISABLED`: 플랫폼 실결제 스위치만 미충족. `details`는 위와 같다
+       *
+       * `sandboxMode: true`는 항상 허용되고 즉시 실결제가 멈춘다.
+       */
+      updateProvider: updatePaymentProvider,
+      /**
+       * 샌드박스 스위치만 바꾼다 — `updateProvider(provider, { sandboxMode })`와 같다.
+       * `false`(라이브 전환)는 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`(둘 다 `ApiError.details.conditions`)가 날 수 있다.
+       */
+      setSandboxMode: (provider: PgProvider, sandboxMode: boolean) =>
+        updatePaymentProvider(provider, { sandboxMode }),
+      /**
+       * `DELETE /v1/store/payment-providers/{provider}` (204) — 연결 해제. 결제 이력과 무관하게 허용된다.
+       * 모든 세트는 보관되고 PG 설정에서 사라진다. 이미 받은 결제의 취소·환불·대사는 보관된 자격 증명으로 계속 처리된다.
+       * 404 `PAYMENT_PROVIDER_NOT_FOUND`.
+       */
+      disconnect: (provider: PgProvider) =>
+        storeHttp.requestVoid(
+          "DELETE",
+          path`/store/payment-providers/${pgProviderSchema.parse(provider)}`,
+        ),
+      /**
+       * `DELETE /v1/store/payment-providers/{provider}/credentials/{TEST|LIVE}` (200) — 활성 환경이 아닌 세트 하나를 보관 처리하고
+       * 갱신된 `PaymentProvider`를 돌려준다. 보관된 세트는 그 세트로 받은 결제의 환불에 계속 쓰인다.
+       *
+       * 에러: 404 `PAYMENT_PROVIDER_NOT_FOUND`(미연결 PG) · 404 `PAYMENT_CREDENTIAL_NOT_FOUND`(등록되지 않은 세트) ·
+       * 409 `PAYMENT_CREDENTIAL_ACTIVE`(지금 결제에 쓰는 세트. 먼저 `setSandboxMode`로 스위치를 바꾼다)
+       */
+      removeCredentialSet: (provider: PgProvider, environment: PgEnvironment) =>
+        storeHttp.request(
+          "DELETE",
+          path`/store/payment-providers/${pgProviderSchema.parse(provider)}/credentials/${pgEnvironmentSchema.parse(environment)}`,
+          paymentProviderSchema,
+        ),
+      /**
+       * `POST /v1/store/payment-providers/{provider}/verify` — 저장된 세트로 연결 테스트하고 결과를 그 세트에 저장한다.
+       * `environment`를 생략하면 활성 환경 세트를 테스트한다. 실패해도 200이고 `result: "FAILED"`와 `message`에 사유가 온다.
+       * 라이브 개방 조건 `TEST_CONNECTION`·`LIVE_CONNECTION`은 이 결과로 판정한다. 404 `PAYMENT_PROVIDER_NOT_FOUND`.
+       */
+      verify: (provider: PgProvider, body?: VerifyPaymentProviderRequest) =>
+        storeHttp.request(
+          "POST",
+          path`/store/payment-providers/${pgProviderSchema.parse(provider)}/verify`,
+          paymentProviderVerificationSchema,
+          { body: verifyPaymentProviderRequestSchema.parse(body ?? {}) },
+        ),
+    },
+
+    webhooks: {
+      list: () => storeHttp.request("GET", "/webhooks", z.array(webhookSchema)),
+      /** 서명 시크릿 평문은 이 응답에서만 노출된다 */
+      create: (body: WebhookRequest) =>
+        storeHttp.request("POST", "/webhooks", webhookCreatedSchema, {
+          body: webhookRequestSchema.parse(body),
+        }),
+      get: (webhookId: string) =>
+        storeHttp.request("GET", path`/webhooks/${webhookId}`, webhookSchema),
+      /** SUSPENDED 구독은 수정하면 ACTIVE로 돌아간다. 수정된 구독을 돌려준다 */
+      update: (webhookId: string, body: WebhookRequest) =>
+        storeHttp.request("PUT", path`/webhooks/${webhookId}`, webhookSchema, {
+          body: webhookRequestSchema.parse(body),
+        }),
+      remove: (webhookId: string) => storeHttp.requestVoid("DELETE", path`/webhooks/${webhookId}`),
+      rotateSecret: (webhookId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/webhooks/${webhookId}/rotate-secret`,
+          webhookSecretRotatedSchema,
+        ),
+      /** SUSPENDED 구독을 ACTIVE로 재개하고 연속 실패 기록을 초기화한다. 이미 ACTIVE면 그대로 돌려준다(멱등) */
+      resume: (webhookId: string) =>
+        storeHttp.request("POST", path`/webhooks/${webhookId}/resume`, webhookSchema),
+      /** 전송 기록 (최신 적재순, 기본 50건·최대 100건, 보관 30일) */
+      listDeliveries: (webhookId: string, params?: WebhookDeliveryListParams) =>
+        storeHttp.request(
+          "GET",
+          path`/webhooks/${webhookId}/deliveries`,
+          z.array(webhookDeliverySchema),
+          { query: params as Query },
+        ),
+      /**
+       * FAILED 전송 기록 한 건을 같은 eventId로 다시 보낸다(202). 새로 적재된 기록을 돌려주며
+       * `redeliveryOf`가 원본 deliveryId다. 원본이 FAILED가 아니면 409 `DELIVERY_NOT_FAILED`,
+       * 원본이 이미 재전송됐으면 409 `DELIVERY_ALREADY_REDELIVERED`(원본당 1회, 원본의 `redeliveredAs` 참고),
+       * 구독이 SUSPENDED면 409 `WEBHOOK_SUSPENDED`.
+       */
+      redeliver: (webhookId: string, deliveryId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/webhooks/${webhookId}/deliveries/${deliveryId}/redeliver`,
+          webhookDeliverySchema,
+        ),
+      /**
+       * 최근 72시간의 FAILED 중 아직 재전송되지 않은 건 전체(최대 500건)를 다시 보낸다(202).
+       * 구독이 SUSPENDED면 409 `WEBHOOK_SUSPENDED` — 먼저 `resume`한다.
+       */
+      redeliverFailed: (webhookId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/webhooks/${webhookId}/deliveries/redeliver-failed`,
+          webhookRedeliverFailedResultSchema,
+        ),
+      /**
+       * 지정한 이벤트 타입의 샘플 페이로드(이벤트 id `evt_test_…`)를 실제로 보내고 수신 서버 응답을
+       * 동기로 돌려준다. 재시도·정지 판정·전송 기록이 없다.
+       */
+      sendTest: (webhookId: string, body: WebhookTestRequest) =>
+        storeHttp.request("POST", path`/webhooks/${webhookId}/test`, webhookTestResultSchema, {
+          body: webhookTestRequestSchema.parse(body),
+        }),
+    },
+
+    /** API 로그 (보관 7일, 콘솔 OWNER/ADMIN) */
+    apiLogs: {
+      /** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+      list: (params?: ApiLogListOptions) =>
+        storeHttp.request("GET", "/api-logs", apiLogPageSchema, {
+          query: params && {
+            ...params,
+            principalType: Array.isArray(params.principalType)
+              ? params.principalType.join(",") || undefined
+              : params.principalType,
+          },
+        }),
+      /** 최근 24시간 요청 수·에러 수 */
+      summary: () => storeHttp.request("GET", "/api-logs/summary", apiLogSummarySchema),
+    },
+
+    reviews: {
+      list: (params?: ReviewListParams) =>
+        storeHttp.request("GET", "/reviews", pageSchema(reviewSchema), { query: params as Query }),
+      get: (reviewId: string) => storeHttp.request("GET", path`/reviews/${reviewId}`, reviewSchema),
+      createReply: (reviewId: string, content: string) =>
+        storeHttp.requestVoid("POST", path`/reviews/${reviewId}/reply`, { body: { content } }),
+      updateReply: (reviewId: string, content: string) =>
+        storeHttp.requestVoid("PUT", path`/reviews/${reviewId}/reply`, { body: { content } }),
+      deleteReply: (reviewId: string) =>
+        storeHttp.requestVoid("DELETE", path`/reviews/${reviewId}/reply`),
+    },
+
+    sellerAddresses: {
+      list: (type?: AddressType) =>
+        storeHttp.request("GET", "/seller-addresses", z.array(sellerAddressSchema), {
+          query: { type },
+        }),
+      create: (body: SellerAddressRequest) =>
+        storeHttp.requestVoid("POST", "/seller-addresses", {
+          body: sellerAddressRequestSchema.parse(body),
+        }),
+      update: (addressId: string, body: SellerAddressRequest) =>
+        storeHttp.requestVoid("PUT", path`/seller-addresses/${addressId}`, {
+          body: sellerAddressRequestSchema.parse(body),
+        }),
+      remove: (addressId: string) =>
+        storeHttp.requestVoid("DELETE", path`/seller-addresses/${addressId}`),
+      setDefault: (addressId: string) =>
+        storeHttp.requestVoid("POST", path`/seller-addresses/${addressId}/default`),
+    },
+
+    store: {
+      get: () => storeHttp.request("GET", "/store", storeSchema),
+      listMembers: () => storeHttp.request("GET", "/store/members", z.array(storeMemberSchema)),
+      listInvitations: () =>
+        storeHttp.request("GET", "/store/invitations", z.array(invitationSchema)),
+    },
+  };
+}
+
+export type StoreClient = ReturnType<typeof createStoreClient>;