@sayren/store-sdk 0.30.20 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.30.20",
+  "version": "0.32.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -162,6 +162,22 @@ import {
   pickupLocationRequestSchema,
   pickupLocationSchema,
 } from "./schemas/fulfillment";
+import {
+  type ClaimCollectCompleteRequest,
+  claimCollectCompleteRequestSchema,
+  type InventoryAdjustmentRequest,
+  type InventoryLevelListQuery,
+  type InventoryLocationRequest,
+  type InventoryMovementListQuery,
+  type InventoryTransferRequest,
+  inventoryAdjustmentRequestSchema,
+  inventoryLevelPageSchema,
+  inventoryLocationRequestSchema,
+  inventoryLocationSchema,
+  inventoryMovementPageSchema,
+  inventoryOperationResultSchema,
+  inventoryTransferRequestSchema,
+} from "./schemas/inventory";
 import {
   type LoginProvider,
   loginProviderTestSchema,
@@ -226,17 +242,24 @@ import {
   paymentRecordPageSchema,
   paymentRefundRecordSchema,
   paymentSettingsSchema,
+  paymentStatusProviderSchema,
+  paymentStatusSchema,
   pgEnvironmentSchema,
   pgProviderSchema,
   type SalesReportParams,
   salesReportQuerySchema,
   salesReportSchema,
+  setPlatformTestKeysRequestSchema,
   type UpdatePaymentProviderRequest,
   type UpdatePaymentSettingsRequest,
+  type UpsertKakaoPayProviderRequest,
+  type UpsertNaverPayProviderRequest,
   type UpsertPortOneProviderRequest,
   type UpsertTossPaymentsProviderRequest,
   updatePaymentProviderRequestSchema,
   updatePaymentSettingsRequestSchema,
+  upsertKakaoPayProviderRequestSchema,
+  upsertNaverPayProviderRequestSchema,
   upsertPortOneProviderRequestSchema,
   upsertTossPaymentsProviderRequestSchema,
   type VerifyPaymentProviderRequest,
@@ -1042,11 +1065,26 @@ export function createStoreClient(options: StoreClientOptions) {
         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) =>
+      /** 수거 완료 — `restock`(이슈 #132)으로 돌아온 조합·재입고 위치를 지정한다. 생략하면 할당 순서·반품지 위치다 */
+      completeCollect: (claimId: string, body?: ClaimCollectCompleteRequest) =>
+        storeHttp.requestVoid("POST", path`/claims/${claimId}/collect/complete`, {
+          ...(body ? { body: claimCollectCompleteRequestSchema.parse(body) } : {}),
+        }),
+      /** 교환 재배송 — `inventoryLocationId`(이슈 #132)로 교환품을 보낼 위치를 지정한다. 생략하면 그 상품의 기준 위치다 */
+      registerRedelivery: (
+        claimId: string,
+        carrierCode: string,
+        trackingNumber: string,
+        options: { inventoryLocationId?: string } = {},
+      ) =>
         storeHttp.requestVoid("POST", path`/claims/${claimId}/redelivery`, {
-          body: { carrierCode, trackingNumber },
+          body: {
+            carrierCode,
+            trackingNumber,
+            ...(options.inventoryLocationId
+              ? { inventoryLocationId: options.inventoryLocationId }
+              : {}),
+          },
         }),
       hold: (claimId: string, reason: string) =>
         storeHttp.request("POST", path`/claims/${claimId}/hold`, claimHoldResultSchema, {
@@ -1395,6 +1433,22 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("PUT", "/store/payment-providers/portone", paymentProviderSchema, {
           body: upsertPortOneProviderRequestSchema.parse(body),
         }),
+      /**
+       * `PUT /v1/store/payment-providers/kakaopay` — 카카오페이(직접 연동) 자격 증명 세트 저장. 규칙·에러는 `upsertTossPayments`와 같다
+       * (가맹점 식별자는 `cid`, 비밀 필드는 `secretKey`). 결제 옵션은 간편결제(`KAKAOPAY`) 하나다.
+       */
+      upsertKakaoPay: (body: UpsertKakaoPayProviderRequest) =>
+        storeHttp.request("PUT", "/store/payment-providers/kakaopay", paymentProviderSchema, {
+          body: upsertKakaoPayProviderRequestSchema.parse(body),
+        }),
+      /**
+       * `PUT /v1/store/payment-providers/naverpay` — 네이버페이 결제형(직접 연동) 자격 증명 세트 저장. 규칙·에러는 `upsertTossPayments`와 같다
+       * (가맹점 식별자는 `clientId`, 비밀 필드는 `clientSecret`). 결제 옵션은 간편결제(`NAVERPAY`) 하나다.
+       */
+      upsertNaverPay: (body: UpsertNaverPayProviderRequest) =>
+        storeHttp.request("PUT", "/store/payment-providers/naverpay", paymentProviderSchema, {
+          body: upsertNaverPayProviderRequestSchema.parse(body),
+        }),
       /**
        * `PATCH /v1/store/payment-providers/{provider}` — 사용 여부(`enabled`)·샌드박스 스위치(`sandboxMode`) 변경.
        * 하나 이상 보내야 한다(아니면 요청 전에 ZodError). 검증을 모두 통과해야 한 번에 적용된다(부분 적용 없음).
@@ -1416,6 +1470,19 @@ export function createStoreClient(options: StoreClientOptions) {
        */
       setSandboxMode: (provider: PgProvider, sandboxMode: boolean) =>
         updatePaymentProvider(provider, { sandboxMode }),
+      /**
+       * `PUT /v1/store/payment-providers/{provider}/platform-test-keys` — 테스트모드 키 활성화. 켜면 sayren 지정 테스트 키를 TEST 세트로 저장하고 PG를 켠다
+       * (OWNER·ADMIN, 에이전트도 쓸 수 있다). 에러: 409 `PLATFORM_TEST_KEYS_UNAVAILABLE`(그 PG의 지정 테스트 키가 없다)
+       */
+      setPlatformTestKeys: (provider: PgProvider, enabled: boolean) =>
+        storeHttp.request(
+          "PUT",
+          path`/store/payment-providers/${pgProviderSchema.parse(provider)}/platform-test-keys`,
+          paymentStatusProviderSchema,
+          { body: setPlatformTestKeysRequestSchema.parse({ enabled }) },
+        ),
+      /** `GET /v1/store/payment-status` — 지원 PG와 연결·사용·테스트모드 키 상태(비밀 값 없음, OWNER·ADMIN·에이전트) */
+      status: () => storeHttp.request("GET", "/store/payment-status", paymentStatusSchema),
       /**
        * `DELETE /v1/store/payment-providers/{provider}` (204) — 연결 해제. 결제 이력과 무관하게 허용된다.
        * 모든 세트는 보관되고 PG 설정에서 사라진다. 이미 받은 결제의 취소·환불·대사는 보관된 자격 증명으로 계속 처리된다.
@@ -1716,6 +1783,50 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /** 픽업 장소 (이슈 #115) — 방문 수령 주문의 수령 장소. 조회 `store:r`, 쓰기 `store:rw`(상점 플랫폼 OWNER·ADMIN) */
+    /**
+     * 위치별 재고 (이슈 #132) — 재고 위치·위치별 가용 재고·재고 조정·실사·이동·변동 내역. 위치 쓰기는 상점 설정 표면(상점 플랫폼 OWNER·ADMIN)이고
+     * 조회는 `inventory:r`, 조정·이동은 `inventory:rw`다. 같은 `idempotencyKey`로 다시 보내면 첫 결과를 돌려준다(다른 본문이면 409)
+     */
+    inventory: {
+      locations: {
+        list: () =>
+          storeHttp.request("GET", "/inventory-locations", z.array(inventoryLocationSchema)),
+        create: (body: InventoryLocationRequest) =>
+          storeHttp.request("POST", "/inventory-locations", inventoryLocationSchema, {
+            body: inventoryLocationRequestSchema.parse(body),
+          }),
+        update: (inventoryLocationId: string, body: InventoryLocationRequest) =>
+          storeHttp.request(
+            "PUT",
+            path`/inventory-locations/${inventoryLocationId}`,
+            inventoryLocationSchema,
+            { body: inventoryLocationRequestSchema.parse(body) },
+          ),
+        remove: (inventoryLocationId: string) =>
+          storeHttp.requestVoid("DELETE", path`/inventory-locations/${inventoryLocationId}`),
+      },
+      /** 커서 페이지네이션 — 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+      levels: (params?: InventoryLevelListQuery) =>
+        storeHttp.request("GET", "/inventory/levels", inventoryLevelPageSchema, {
+          query: params,
+        }),
+      /** 순번 오름차순 — 다음 쪽은 `nextAfter`를 `after`로 넘긴다 */
+      movements: (params?: InventoryMovementListQuery) =>
+        storeHttp.request("GET", "/inventory/movements", inventoryMovementPageSchema, {
+          query: params,
+        }),
+      adjust: (body: InventoryAdjustmentRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/inventory/adjustments", inventoryOperationResultSchema, {
+          body: inventoryAdjustmentRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      transfer: (body: InventoryTransferRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/inventory/transfers", inventoryOperationResultSchema, {
+          body: inventoryTransferRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+    },
+
     pickupLocations: {
       list: () => storeHttp.request("GET", "/pickup-locations", z.array(pickupLocationSchema)),
       create: (body: PickupLocationRequestInput) =>

package/src/index.ts

@@ -33,6 +33,7 @@ export * from "./schemas/coupon";
 export * from "./schemas/customer";
 export * from "./schemas/customer-delegation";
 export * from "./schemas/fulfillment";
+export * from "./schemas/inventory";
 export * from "./schemas/login";
 export * from "./schemas/misc";
 export * from "./schemas/order";

package/src/schemas/ai.ts

@@ -113,9 +113,16 @@ export type AiToolChange = z.infer<typeof aiToolChangeSchema>;
 
 /**
  * 에이전트 작업 단계(2026-10-13, AI 상점 도우미 작업 공간) — 에이전트가 패널 도구로 알린다.
- * 상점·상품·배포 준비 → 쇼핑몰 구조 설계 → 개발 환경 준비(라이브러리·SDK) → 코드 수정 루프 → 완료
+ * 상점·상품·배포 준비 → 쇼핑몰 구조 설계 → 디자인(아트보드, 2026-10-14 사용자 결정) → 개발 환경 준비(라이브러리·SDK) → 코드 수정 루프 → 완료
  */
-export const AI_AGENT_PHASES = ["STORE", "STRUCTURE", "ENVIRONMENT", "BUILD", "DONE"] as const;
+export const AI_AGENT_PHASES = [
+  "STORE",
+  "STRUCTURE",
+  "DESIGN",
+  "ENVIRONMENT",
+  "BUILD",
+  "DONE",
+] as const;
 export const aiAgentPhaseSchema = z.enum(AI_AGENT_PHASES);
 export type AiAgentPhase = z.infer<typeof aiAgentPhaseSchema>;
 
@@ -145,11 +152,106 @@ export function isAiAgentNotesPath(path: string): boolean {
   return path === AI_AGENT_NOTES_DIR || path.startsWith(`${AI_AGENT_NOTES_DIR}/`);
 }
 
+/**
+ * 디자인 아트보드 폴더(2026-10-14 사용자 결정, Claude Code Design 캔버스의 파일 계약을 옮겼다) — DESIGN 단계에 에이전트가 쓰는 자기완결 HTML 아트보드와
+ * 인덱스 `canvas.json`이다. 앱 코드가 import하지 않아 발행 빌드에 들어가지 않고, 상점 플랫폼 작업 공간의 디자인 탭이 iframe(srcdoc)으로 그린다.
+ * 코드 탭 트리에서는 작업 메모처럼 뺀다
+ */
+export const AI_DESIGN_DIR = "src/site/design";
+export const AI_DESIGN_CANVAS_PATH = `${AI_DESIGN_DIR}/canvas.json`;
+export function isAiDesignPath(path: string): boolean {
+  return path === AI_DESIGN_DIR || path.startsWith(`${AI_DESIGN_DIR}/`);
+}
+/** 아트보드 파일 이름 — `src/site/design/` 바로 아래의 `.html` 하나(폴더 없음) */
+export const AI_DESIGN_BOARD_FILE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}\.html$/;
+export const AI_DESIGN_BOARD_KINDS = ["direction", "page", "scene"] as const;
+export const AI_DESIGN_VIEWPORTS = ["desktop", "mobile"] as const;
+/** 아트보드 상한 — 사이트맵의 화면마다 아트보드를 그린다(2026-10-15 사용자 결정, 화면 로드맵 29개 + 방향 후보 + 모바일). 24에서 올렸다 */
+export const AI_DESIGN_BOARDS_MAX = 64;
+/**
+ * 아트보드 하나 — `file`은 `src/site/design/` 아래 파일 이름, `kind`는 방향(저충실 후보)·페이지(고충실 화면)·장면(모션 시안, 셀러가 스크롤하며 본다),
+ * `viewport`는 데스크톱(1280)·모바일(390) 폭, `page`는 그 아트보드가 그리는 사이트 경로(구현 대조에 쓴다), `status`는 후보·채택·보관
+ */
+export const aiDesignBoardSchema = z.object({
+  file: z.string().regex(AI_DESIGN_BOARD_FILE_PATTERN),
+  title: z.string().min(1).max(60),
+  kind: z.enum(AI_DESIGN_BOARD_KINDS),
+  viewport: z.enum(AI_DESIGN_VIEWPORTS).default("desktop"),
+  page: z.string().max(200).optional(),
+  status: z.enum(["candidate", "chosen", "archived"]).default("chosen"),
+});
+export type AiDesignBoard = z.infer<typeof aiDesignBoardSchema>;
+export const aiDesignCanvasSchema = z.object({
+  version: z.literal(1),
+  /** 정한 방향 이름 — 방향 선택지에서 셀러가 고른 뒤 적는다(이름을 바꾸지 않는다) */
+  direction: z.string().max(80).nullable().default(null),
+  boards: z.array(aiDesignBoardSchema).max(AI_DESIGN_BOARDS_MAX),
+  /** 캔버스에 붙이는 메모(장 전환 규칙 등) */
+  notes: z.array(z.string().max(300)).max(20).default([]),
+});
+export type AiDesignCanvas = z.infer<typeof aiDesignCanvasSchema>;
+
+/** 셀러가 디자인 탭에서 고른 아트보드(2026-10-14) — 메시지와 함께 보내면 모델은 그 아트보드를 기준으로 고친다 */
+export const aiDesignSelectionSchema = z.object({
+  file: z.string().regex(AI_DESIGN_BOARD_FILE_PATTERN),
+  title: z.string().max(60),
+});
+export type AiDesignSelection = z.infer<typeof aiDesignSelectionSchema>;
+
+/** 쇼핑몰 형태(#124, 2026-10-13) — 템플릿은 basic 하나이고 형태는 에이전트에게 주는 화면 구성 지시다 */
+export const STORE_SHOP_TYPES = [
+  "BASIC",
+  "INTERACTIVE",
+  "STORYTELLING",
+  "MOBILE",
+  "CATALOG",
+  "LOOKBOOK",
+] as const;
+export const storeShopTypeSchema = z.enum(STORE_SHOP_TYPES);
+export type StoreShopType = z.infer<typeof storeShopTypeSchema>;
+
+/**
+ * 선택지 하나 — `templateId`는 스토어프론트 템플릿을, `shopType`은 쇼핑몰 형태를 고르는 선택지일 때의 값이다(2026-10-14). 상점 플랫폼이 썸네일을 붙인다
+ */
+export const aiChoiceOptionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+  templateId: z.string().max(64).optional(),
+  /** 쇼핑몰 형태를 고르는 선택지면 그 형태 — 상점 플랫폼이 형태 와이어프레임을 붙인다 */
+  shopType: storeShopTypeSchema.optional(),
+  /** 디자인 방향을 고르는 선택지면 그 아트보드 파일(`src/site/design/` 아래) — 상점 플랫폼이 아트보드를 썸네일로 붙인다(2026-10-14) */
+  boardFile: z.string().regex(AI_DESIGN_BOARD_FILE_PATTERN).optional(),
+});
+export type AiChoiceOption = z.infer<typeof aiChoiceOptionSchema>;
+
+/**
+ * 쇼핑몰 만들기 확인(2026-10-14) — 에이전트가 대화로 모은 값(라벨·값)과 고른 템플릿을 보이고 「이렇게 쇼핑몰을 만들까요?」를 묻는다.
+ * 셀러가 승인(`AI_SETUP_CONFIRM_APPROVE` 선택지)하면 만들기를 시작한다
+ */
+export const aiSetupConfirmItemSchema = z.object({ label: z.string(), value: z.string() });
+export type AiSetupConfirmItem = z.infer<typeof aiSetupConfirmItemSchema>;
+/** 확인 카드의 승인 선택지 값 */
+export const AI_SETUP_CONFIRM_APPROVE = "setup:approve";
+
+/**
+ * 디자인 확인(2026-10-14 사용자 결정) — DESIGN 단계 끝에 에이전트가 채택한 아트보드를 카드로 보이고 「이 디자인으로 만들까요?」를 묻는다.
+ * 셀러가 승인(`AI_DESIGN_CONFIRM_APPROVE` 선택지)해야 구현(ENVIRONMENT·BUILD)으로 넘어간다
+ */
+export const aiDesignConfirmBoardSchema = z.object({
+  file: z.string().regex(AI_DESIGN_BOARD_FILE_PATTERN),
+  title: z.string().max(60),
+});
+export type AiDesignConfirmBoard = z.infer<typeof aiDesignConfirmBoardSchema>;
+export const AI_DESIGN_CONFIRM_APPROVE = "design:approve";
+
 /**
  * 화면에 그리는 메시지 조각. 모델 원문(tool_use 블록 등)은 api가 보관하고 화면에는 이 형태만 준다.
  * - `text`: 글
  * - `tool`: 도구 호출 한 번(이름은 사람이 읽는 라벨, 결과 요약·링크)
  * - `choices`: 선택지 버튼(가장 최근 것만 누를 수 있다)
+ * - `setup_confirm`: 쇼핑몰 만들기 확인 카드(모은 값·템플릿, 승인은 뒤따르는 `choices`)
+ * - `design_confirm`: 디자인 확인 카드(채택한 아트보드, 승인은 뒤따르는 `choices`)
+ * - `design_selection`: 사용자가 디자인 탭에서 고른 아트보드
  * - `business_form`: 사업자 정보 입력 폼(가장 최근 것만 제출할 수 있다, 건너뛸 수 있다)
  * - `attachment`: 사용자가 올린 첨부
  * - `approval`: 승인 대기로 남은 쓰기
@@ -176,13 +278,23 @@ export const aiMessagePartSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("choices"),
     question: z.string(),
-    options: z
-      .array(z.object({ label: z.string(), value: z.string() }))
-      .min(1)
-      .max(6),
+    options: z.array(aiChoiceOptionSchema).min(1).max(6),
   }),
   z.object({ type: z.literal("business_form"), question: z.string() }),
+  /** 쇼핑몰 만들기 확인 카드 — 아래 선택지 조각이 승인을 묻는다 */
+  z.object({
+    type: z.literal("setup_confirm"),
+    items: z.array(aiSetupConfirmItemSchema).max(12),
+    templateId: z.string().max(64).optional(),
+  }),
+  /** 디자인 확인 카드 — 채택한 아트보드, 아래 선택지 조각이 승인을 묻는다 */
+  z.object({
+    type: z.literal("design_confirm"),
+    boards: z.array(aiDesignConfirmBoardSchema).min(1).max(AI_DESIGN_BOARDS_MAX),
+  }),
   z.object({ type: z.literal("attachment"), attachment: aiAttachmentSchema }),
+  /** 사용자가 디자인 탭에서 고른 아트보드 */
+  z.object({ type: z.literal("design_selection"), selection: aiDesignSelectionSchema }),
   /** 공개 뒤 승인이 필요한 쓰기를 승인 요청으로 남겼다(셀러가 승인함에서 결정한다) */
   z.object({ type: z.literal("approval"), approvalId: z.string(), title: z.string() }),
   /** 사용자가 미리보기에서 고른 요소(#65) */
@@ -220,18 +332,6 @@ export const aiConversationSchema = aiConversationSummarySchema.extend({
 });
 export type AiConversation = z.infer<typeof aiConversationSchema>;
 
-/** 쇼핑몰 형태(#124, 2026-10-13) — 템플릿은 basic 하나이고 형태는 에이전트에게 주는 화면 구성 지시다 */
-export const STORE_SHOP_TYPES = [
-  "BASIC",
-  "INTERACTIVE",
-  "STORYTELLING",
-  "MOBILE",
-  "CATALOG",
-  "LOOKBOOK",
-] as const;
-export const storeShopTypeSchema = z.enum(STORE_SHOP_TYPES);
-export type StoreShopType = z.infer<typeof storeShopTypeSchema>;
-
 /**
  * AI 상점 만들기 질문 화면의 답(#124, 2026-10-13) — 화면이 고정 질문으로 모은다. 초안과 함께 첫 메시지가 된다.
  * 배송비는 묻지 않는다(설정하지 않으면 무료배송). `slug`는 바라는 주소이고 쓸 수 있는지는 에이전트가 사이트를 만들 때 확인한다
@@ -270,6 +370,8 @@ export const sendAiMessageRequestSchema = z
     choice: z.string().max(200).optional(),
     /** 편집 미리보기에서 고른 요소(#65) — 모델은 이 요소를 기준으로 고친다 */
     selection: aiPreviewSelectionSchema.optional(),
+    /** 디자인 탭에서 고른 아트보드(2026-10-14) — 모델은 그 아트보드를 기준으로 고친다 */
+    designSelection: aiDesignSelectionSchema.optional(),
   })
   .refine((body) => body.text.length > 0 || body.attachments.length > 0, {
     message: "내용이나 첨부가 있어야 합니다",
@@ -430,10 +532,23 @@ export const aiStreamEventSchema = z.discriminatedUnion("type", [
     type: z.literal("choices"),
     messageId: z.string(),
     question: z.string(),
-    options: z.array(z.object({ label: z.string(), value: z.string() })),
+    options: z.array(aiChoiceOptionSchema),
   }),
   /** 사업자 정보 입력 폼을 보였다 — 답은 다음 메시지로 온다 */
   z.object({ type: z.literal("business_form"), messageId: z.string(), question: z.string() }),
+  /** 쇼핑몰 만들기 확인 카드를 보였다 — 이어서 승인 선택지(`choices`)가 온다 */
+  z.object({
+    type: z.literal("setup_confirm"),
+    messageId: z.string(),
+    items: z.array(aiSetupConfirmItemSchema),
+    templateId: z.string().max(64).optional(),
+  }),
+  /** 디자인 확인 카드를 보였다 — 이어서 승인 선택지(`choices`)가 온다 */
+  z.object({
+    type: z.literal("design_confirm"),
+    messageId: z.string(),
+    boards: z.array(aiDesignConfirmBoardSchema),
+  }),
   /** 공개 뒤 승인이 필요한 쓰기를 승인 요청으로 남겼다 */
   z.object({
     type: z.literal("approval"),

package/src/schemas/app-manifest.ts

@@ -140,6 +140,7 @@ export const APP_EVENT_SCOPES: Record<AppEventType, string | null> = {
   "INQUIRY.CREATED": "inquiry:r",
   "REVIEW.CREATED": "review:r",
   "PRODUCT.OUT_OF_STOCK": "product:r",
+  "INVENTORY.CHANGED": "inventory:r",
   "APP.INSTALLED": null,
   "APP.UNINSTALLED": null,
   "APP.SETTINGS_UPDATED": null,

package/src/schemas/fulfillment.ts

@@ -476,6 +476,13 @@ export const pickupLocationSchema = z.object({
   hours: z.string().nullable().describe("수령 가능 시간 안내. 없으면 null"),
   usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 주문서에서 고를 수 없다"),
   sortOrder: z.number().int(),
+  inventoryLocationId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "이 장소의 재고 위치 ID — 방문 수령 주문을 이 위치 재고로 판다. 위치를 하나만 쓰는 상점은 기본 위치다",
+    ),
   createdAt: z.string(),
 });
 
@@ -487,6 +494,11 @@ export const pickupLocationRequestSchema = z.strictObject({
   phone: z.string().trim().max(30).nullish(),
   hours: z.string().trim().max(100).nullish(),
   usable: z.boolean().default(true),
+  inventoryLocationId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("재고 위치 ID. 등록에서 생략하면 기본 위치, 수정에서 생략하면 지금 연결을 유지한다"),
 });
 
 export type PickupLocationRequest = z.infer<typeof pickupLocationRequestSchema>;

package/src/schemas/inventory.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+
+/**
+ * 위치별 재고 (이슈 #132) — 재고 위치(창고·상설 매장·팝업 매장)마다 조합의 가용 재고를 따로 센다. 출고지·반품지·픽업 장소가 위치를
+ * 가리키고, 배송 주문은 출고지 위치에서, 방문 수령 주문은 그 매장 위치에서 뺀다. 위치를 하나만 쓰는 상점은 기본 위치 하나다.
+ *
+ * - 가용 재고(`available`)는 지금 팔 수 있는 수량이다(팔린 미출고분이 이미 빠진 수). 저장하는 값이다.
+ * - 출고 대기(`pendingFulfillment`)는 그 위치에 할당됐고 아직 출고 전(주문상품 `PAID`·`CONFIRMED`)인 수량이다.
+ * - 실재고(`onHand`)는 가용 재고 + 출고 대기다. 위치에 실제로 있어야 하는 수량이다.
+ * - 상품·옵션 API의 `stockQuantity`는 그 상품 기준 위치의 가용 재고다(이름·뜻 유지).
+ */
+
+/** 재고 조정 사유 — `COUNT`는 실사 줄(`counted`)이 쓴다 */
+export const inventoryAdjustmentReasonSchema = z
+  .enum(["RECEIVED", "DAMAGED", "LOST", "FOUND", "RETURN_RESTOCK", "CORRECTION", "COUNT"])
+  .describe(
+    "조정 사유 — 입고 `RECEIVED`, 파손 `DAMAGED`, 분실 `LOST`, 재발견 `FOUND`, 반품 재입고 `RETURN_RESTOCK`, 정정 `CORRECTION`, 실사 `COUNT`",
+  );
+export type InventoryAdjustmentReason = z.infer<typeof inventoryAdjustmentReasonSchema>;
+
+export const inventoryLocationSchema = z.object({
+  inventoryLocationId: z.string(),
+  name: z.string().describe("위치 이름(예: 본사 창고, 성수 팝업)"),
+  isDefault: z
+    .boolean()
+    .describe("기본 위치인가 — 상점마다 하나이고 삭제할 수 없다. 기존 재고가 있는 곳이다"),
+  sortOrder: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type InventoryLocation = z.infer<typeof inventoryLocationSchema>;
+
+export const inventoryLocationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50),
+  sortOrder: z.number().int().min(0).max(10_000).optional(),
+});
+export type InventoryLocationRequest = z.infer<typeof inventoryLocationRequestSchema>;
+
+export const inventoryLevelSchema = z.object({
+  productId: z.string(),
+  variantId: z
+    .string()
+    .describe("판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z.string(),
+  available: z.number().int().describe("가용 재고"),
+  pendingFulfillment: z.number().int().describe("출고 대기 — 할당됐고 아직 출고 전인 수량"),
+  onHand: z.number().int().describe("실재고 — 가용 재고 + 출고 대기"),
+  version: z
+    .number()
+    .int()
+    .describe("쓰기마다 1씩 오르는 버전(`INVENTORY.CHANGED`의 `levelVersion`)"),
+  updatedAt: z.string(),
+});
+export type InventoryLevel = z.infer<typeof inventoryLevelSchema>;
+
+export const inventoryLevelListQuerySchema = z.object({
+  inventoryLocationId: z.string().optional(),
+  productId: z.string().optional(),
+  variantId: z.string().optional(),
+  cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 처음부터"),
+  limit: z.coerce.number().int().min(1).max(200).optional().describe("한 쪽 크기(기본 100)"),
+});
+export type InventoryLevelListQuery = z.infer<typeof inventoryLevelListQuerySchema>;
+
+export const inventoryLevelPageSchema = z.object({
+  contents: z.array(inventoryLevelSchema),
+  nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null"),
+});
+export type InventoryLevelPage = z.infer<typeof inventoryLevelPageSchema>;
+
+export const inventoryMovementKindSchema = z
+  .enum([
+    "OPENING",
+    "SALE",
+    "RESTORE",
+    "REVERT",
+    "EXCHANGE_OUT",
+    "ADJUST",
+    "COUNT",
+    "TRANSFER_OUT",
+    "TRANSFER_IN",
+    "REMOVED",
+  ])
+  .describe(
+    "변동 종류 — 시작 `OPENING`, 판매 `SALE`, 복원 `RESTORE`, 복원 되돌리기 `REVERT`, 교환 출고 `EXCHANGE_OUT`, 조정 `ADJUST`, 실사 `COUNT`, 이동 출고 `TRANSFER_OUT`, 이동 입고 `TRANSFER_IN`, 조합 삭제 `REMOVED`",
+  );
+export type InventoryMovementKind = z.infer<typeof inventoryMovementKindSchema>;
+
+export const inventoryMovementSchema = z.object({
+  movementId: z.string(),
+  seq: z
+    .number()
+    .int()
+    .describe("상점별 순번 — 커밋 순서와 같고 빈 번호가 없다. `after` 커서에 쓴다"),
+  productId: z.string(),
+  variantId: z.string(),
+  inventoryLocationId: z.string(),
+  kind: z.string().describe("변동 종류(`inventoryMovementKindSchema`). 값이 늘 수 있다"),
+  delta: z.number().int().describe("가용 재고 변화량"),
+  available: z.number().int().describe("변화 뒤 가용 재고"),
+  levelVersion: z.number().int(),
+  reason: z.string().nullable(),
+  note: z.string().nullable(),
+  refType: z.string().nullable().describe("출처 유형 — `order_item`·`claim`·`operation`"),
+  refId: z.string().nullable(),
+  operationId: z.string().nullable().describe("재고 조정·이동 요청 ID"),
+  actorType: z.string().describe("행위자 유형 — `seller`·`app`·`agent`·`system`"),
+  actorId: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type InventoryMovement = z.infer<typeof inventoryMovementSchema>;
+
+export const inventoryMovementListQuerySchema = z.object({
+  inventoryLocationId: z.string().optional(),
+  productId: z.string().optional(),
+  variantId: z.string().optional(),
+  kind: inventoryMovementKindSchema.optional(),
+  after: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("이 순번 다음부터(오름차순). 생략하면 처음부터"),
+  from: z.string().optional().describe("이 시각 이후(ISO 8601)"),
+  to: z.string().optional().describe("이 시각 이전(ISO 8601)"),
+  limit: z.coerce.number().int().min(1).max(200).optional().describe("한 쪽 크기(기본 100)"),
+});
+export type InventoryMovementListQuery = z.infer<typeof inventoryMovementListQuerySchema>;
+
+export const inventoryMovementPageSchema = z.object({
+  contents: z.array(inventoryMovementSchema),
+  nextAfter: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "다음 쪽의 `after` 값. 더 없으면 null(새 변동을 기다릴 때는 마지막 `seq`를 그대로 쓴다)",
+    ),
+});
+export type InventoryMovementPage = z.infer<typeof inventoryMovementPageSchema>;
+
+/** 한 요청의 줄 상한 — 30초 타임아웃·바인드 한도 */
+export const MAX_INVENTORY_OPERATION_LINES = 200;
+
+export const inventoryAdjustmentLineSchema = z
+  .strictObject({
+    variantId: z.string().min(1),
+    inventoryLocationId: z.string().min(1).optional().describe("생략하면 기본 위치"),
+    delta: z
+      .number()
+      .int()
+      .refine((value) => value !== 0, { message: "delta는 0이 아니어야 합니다" })
+      .optional()
+      .describe("가용 재고 증감. 감소는 가용 재고를 넘지 않는다"),
+    counted: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "실사 — 센 실물 수량. 실재고가 이 값이 되도록 가용 재고를 맞춘다(센 값 − 출고 대기)",
+      ),
+  })
+  .refine((line) => (line.delta === undefined) !== (line.counted === undefined), {
+    message: "줄마다 delta와 counted 중 하나만 줍니다",
+  });
+
+export const inventoryAdjustmentRequestSchema = z.strictObject({
+  lines: z.array(inventoryAdjustmentLineSchema).min(1).max(MAX_INVENTORY_OPERATION_LINES),
+  reason: inventoryAdjustmentReasonSchema
+    .optional()
+    .describe("증감 줄(`delta`)의 사유. 실사 줄은 늘 `COUNT`다. 증감 줄이 있으면 필수"),
+  note: z.string().trim().max(500).optional(),
+  reference: z.string().trim().max(100).optional().describe("외부 참조(입고서 번호 등)"),
+});
+export type InventoryAdjustmentRequest = z.infer<typeof inventoryAdjustmentRequestSchema>;
+
+export const inventoryTransferRequestSchema = z.strictObject({
+  fromInventoryLocationId: z.string().min(1),
+  toInventoryLocationId: z.string().min(1),
+  lines: z
+    .array(z.strictObject({ variantId: z.string().min(1), quantity: z.number().int().min(1) }))
+    .min(1)
+    .max(MAX_INVENTORY_OPERATION_LINES),
+  note: z.string().trim().max(500).optional(),
+});
+export type InventoryTransferRequest = z.infer<typeof inventoryTransferRequestSchema>;
+
+export const inventoryOperationResultSchema = z.object({
+  operationId: z.string(),
+  kind: z.enum(["ADJUSTMENT", "TRANSFER"]),
+  lines: z.array(
+    z.object({
+      variantId: z.string(),
+      inventoryLocationId: z.string(),
+      delta: z.number().int().describe("적용한 가용 재고 변화량(실사는 맞춘 차이, 같으면 0)"),
+      available: z.number().int().describe("적용 뒤 가용 재고"),
+    }),
+  ),
+  createdAt: z.string(),
+});
+export type InventoryOperationResult = z.infer<typeof inventoryOperationResultSchema>;
+
+/** 수거 완료의 재입고 지정(Q3) — 생략하면 조합은 할당 순서(교환 → 판매), 위치는 반품지에 연결된 위치 → 할당 위치다 */
+export const claimCollectCompleteRequestSchema = z.object({
+  restock: z
+    .object({
+      optionId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "돌아온 조합 — 그 주문상품의 할당 조합이어야 한다(아니면 400 `INVALID_RESTOCK_OPTION`)",
+        ),
+      inventoryLocationId: z.string().min(1).optional().describe("재입고할 재고 위치"),
+    })
+    .optional(),
+});
+export type ClaimCollectCompleteRequest = z.infer<typeof claimCollectCompleteRequestSchema>;
+
+export const claimRedeliveryRequestSchema = z.object({
+  carrierCode: z.string().min(1),
+  trackingNumber: z.string().min(1),
+  inventoryLocationId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("교환품을 보낼 재고 위치. 생략하면 그 상품의 기준 위치"),
+});
+export type ClaimRedeliveryRequest = z.infer<typeof claimRedeliveryRequestSchema>;

package/src/schemas/misc.ts

@@ -162,6 +162,8 @@ export const eventTypeSchema = z
     "ORDER.FLOW_NOTIFICATION",
     // 커머스 플로우 상태 변경(이슈 #115). 흐름 단계가 바뀔 때마다 간다
     "ORDER.FLOW_STATE_CHANGED",
+    // 위치별 재고 변화(이슈 #132). 재고 변동 내역 한 행마다 간다
+    "INVENTORY.CHANGED",
   ])
   .describe(
     "웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",