@sayren/store-sdk 0.31.0 → 0.33.0

package/src/schemas/product.ts

@@ -1,5 +1,12 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
+import { BASE_CURRENCY, CURRENCIES } from "./currency";
+import {
+  additionalCurrencyPricesSchema,
+  productCurrencyPricesSchema,
+  storedAdditionalCurrencyPriceSchema,
+  storedProductCurrencyPriceSchema,
+} from "./currency-prices";
 import {
   fulfillmentTypeResponseSchema,
   productFulfillmentCreateSchema,
@@ -95,6 +102,10 @@ export const productVariantSchema = z.object({
   /** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
   name: z.string(),
   additionalPrice: z.number().int(),
+  prices: z
+    .array(storedAdditionalCurrencyPriceSchema)
+    .optional()
+    .describe("외화 추가금(이슈 #130, 관리 API만). 기본 통화 값은 `additionalPrice`다"),
   stockQuantity: z.number().int(),
   sku: z.string().nullable(),
   barcode: z.string().nullable(),
@@ -154,6 +165,10 @@ export const addonValueSchema = z.object({
   name: z.string(),
   sortOrder: z.number().int(),
   additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
+  prices: z
+    .array(storedAdditionalCurrencyPriceSchema)
+    .optional()
+    .describe("외화 추가금(이슈 #130, 관리 API만). 기본 통화 값은 `additionalPrice`다"),
   usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 고를 수 없다"),
 });
 
@@ -272,6 +287,7 @@ export const addonValueRequestSchema = z.object({
   valueId: z.string().optional(),
   name: optionNameSchema,
   additionalPrice: z.number().int().min(0).default(0).describe("추가금(원, 0 이상)"),
+  prices: additionalCurrencyPricesSchema.optional(),
   usable: z.boolean().default(true),
 });
 
@@ -350,6 +366,10 @@ export const discountSchema = z.object({
 export type Discount = z.infer<typeof discountSchema>;
 
 export const productSchema = productSummarySchema.extend({
+  prices: z
+    .array(storedProductCurrencyPriceSchema)
+    .optional()
+    .describe("외화 판매가(이슈 #130). 기본 통화 값은 `salePrice`·`originalPrice`다"),
   description: z.string().optional(),
   /**
    * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -516,6 +536,7 @@ export const productVariantRequestSchema = z.object({
   /** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
   valueNames: z.array(z.string()).default([]),
   additionalPrice: z.number().int().default(0),
+  prices: additionalCurrencyPricesSchema.optional(),
   /**
    * 생략 = 기존 재고 유지 (신규 variant는 0).
    * 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
@@ -627,14 +648,20 @@ const productImagesRequestSchema = z.array(productImageUrlSchema).min(1).max(MAX
  * 최상위가 `strictObject`다. 모르는 필드는 400이다 — 이슈 #57 이전의 평면 필드(`deliveryFee`·`fulfillmentType`·`returnFee` 등)를
  * 보낸 요청이 조용히 무시되지 않게 한다. 옛 필드는 `fulfillment.{유형}.…`과 `refundPolicy`로 옮겼다.
  */
+/**
+ * 기본 통화 판매가 단위 — 통화표가 원천이다(이슈 #130). zod `multipleOf`로 두어 OpenAPI에 그대로 드러난다.
+ * 외화 판매가(`prices[]`)는 통화마다 `isSaleUnitPrice`로 검사한다
+ */
+const BASE_SALE_UNIT = CURRENCIES[BASE_CURRENCY].saleUnit;
+
 const productWriteShape = {
   name: z.string().min(1).max(100),
   categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
   salePrice: z
     .number()
     .int()
-    .min(10)
-    .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
+    .min(BASE_SALE_UNIT)
+    .multipleOf(BASE_SALE_UNIT, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
     .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
   originalPrice: z
     .number()
@@ -650,6 +677,7 @@ const productWriteShape = {
     .describe(
       "구매 적립률 덮어쓰기(만분율, 100 = 1%, 0~3000, 이슈 #93). null이면 상점 기본 적립률, 0이면 이 상품은 적립하지 않는다. 결제 확정 시점 값이 주문상품에 남는다. 전체 수정(PUT)에서 생략하면 지금 값을 유지한다",
     ),
+  prices: productCurrencyPricesSchema.optional(),
   description: z.string().optional(),
   /**
    * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -717,7 +745,7 @@ export type ProductReplaceRequestInput = z.input<typeof productReplaceRequestSch
 export const productPatchRequestSchema = z
   .strictObject({
     name: z.string().max(100).optional(),
-    salePrice: z.number().int().multipleOf(10).optional(),
+    salePrice: z.number().int().multipleOf(BASE_SALE_UNIT).optional(),
     status: productStatusSchema.optional(),
     flowId: z
       .string()
@@ -732,6 +760,7 @@ export const productPatchRequestSchema = z
         "상품 이미지 주소 목록. 주면 통째로 바꾼다(현재 목록과 병합하지 않는다). 첫 장이 대표 이미지(썸네일)다. 생략하면 바꾸지 않는다",
       ),
     fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
+    prices: productCurrencyPricesSchema.optional(),
     refundPolicy: productRefundPolicyPatchSchema
       .nullable()
       .optional()

package/src/schemas/promotion.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CURRENCIES, KRW_MONEY_RULES, type MoneyRules } from "./currency";
 import { proratedRefundBase } from "./refund-policy";
 
 /**
@@ -172,7 +173,7 @@ export const couponRejectReasonSchema = z
 export type CouponRejectReason = z.infer<typeof couponRejectReasonSchema>;
 
 /** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
-export const MIN_PAYMENT_AMOUNT = 100;
+export const MIN_PAYMENT_AMOUNT = CURRENCIES.KRW.minPayment;
 
 // ─── 계산 ─────────────────────────────────────────────
 
@@ -259,6 +260,11 @@ export interface PricingInput {
    * 것처럼 보이고, 탈퇴한 회원의 반품이 회원 전용 조건에 떨어진다. 대상과 최소 금액만 본다.
    */
   ignoreEligibility?: boolean;
+  /**
+   * 주문 통화의 규칙 값(이슈 #130) — 정률 할인 내림 단위(판매가 단위)와 적립금 사용 뒤 남길 최소 결제액. 생략하면 KRW 규칙이다.
+   * 금액 입력은 모두 이 통화의 최소 단위다
+   */
+  moneyRules?: MoneyRules;
 }
 
 /** 줄 하나에 들어간 쿠폰별 할인 */
@@ -325,15 +331,22 @@ export interface PricingResult {
 }
 
 /**
- * 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
+ * 할인액 — 정률은 판매가 단위(`rules.saleUnit`, KRW 10원) 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
  *
- * 곱셈을 먼저 하고 나눈다. `base × 율 ÷ 1000`을 내려 10을 곱하면 `floor(base × 율 / 100 / 10) × 10`과 같고
- * 부동소수 오차가 끼지 않는다.
+ * 곱셈을 먼저 하고 나눈다. `base × 율 ÷ (100 × 단위)`를 내려 단위를 곱하면 `floor(base × 율 / 100 / 단위) × 단위`와 같고
+ * 부동소수 오차가 끼지 않는다(KRW는 지금의 `÷ 1000 × 10` 그대로).
  */
-export function couponDiscountOf(benefit: CouponBenefit, base: number): number {
+export function couponDiscountOf(
+  benefit: CouponBenefit,
+  base: number,
+  rules: MoneyRules = KRW_MONEY_RULES,
+): number {
   if (base <= 0) return 0;
+  const unit = rules.saleUnit;
   let raw =
-    benefit.type === "RATE" ? Math.floor((base * benefit.value) / 1000) * 10 : benefit.value;
+    benefit.type === "RATE"
+      ? Math.floor((base * benefit.value) / (100 * unit)) * unit
+      : benefit.value;
   if (benefit.type === "RATE" && benefit.maxDiscountAmount !== null) {
     raw = Math.min(raw, benefit.maxDiscountAmount);
   }
@@ -422,6 +435,7 @@ function periodRejectOf(coupon: PricingCoupon, now: Date): CouponRejectReason |
  * 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
  */
 export function quotePricing(input: PricingInput): PricingResult {
+  const rules = input.moneyRules ?? KRW_MONEY_RULES;
   const lines = input.lines.map((line) => ({
     line,
     productDiscount: 0,
@@ -516,14 +530,14 @@ export function quotePricing(input: PricingInput): PricingResult {
         continue;
       }
       chosen = coupon.lineId;
-      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0);
+      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0, rules);
     } else {
       if (candidates.length === 0) {
         result.rejectReason = "STACK_LIMIT";
         continue;
       }
       for (const id of candidates) {
-        const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0);
+        const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0, rules);
         if (chosen === null || discount > best) {
           chosen = id;
           best = discount;
@@ -557,7 +571,7 @@ export function quotePricing(input: PricingInput): PricingResult {
       .filter((entry): entry is (typeof lines)[number] => entry !== undefined);
     const weights = targets.map((entry) => Math.max(0, entry.line.amount - entry.productDiscount));
     const base = weights.reduce((sum, w) => sum + w, 0);
-    const discount = couponDiscountOf(coupon.rule.benefit, base);
+    const discount = couponDiscountOf(coupon.rule.benefit, base, rules);
     if (discount <= 0) {
       result.rejectReason = "NO_DISCOUNT";
       continue;
@@ -591,7 +605,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     }
     const weights = deliveryBundles.map((bundle) => Math.max(0, bundle.fee));
     const base = weights.reduce((sum, w) => sum + w, 0);
-    const discount = couponDiscountOf(coupon.rule.benefit, base);
+    const discount = couponDiscountOf(coupon.rule.benefit, base, rules);
     if (discount <= 0) {
       result.rejectReason = "NO_DISCOUNT";
       continue;
@@ -625,11 +639,15 @@ export function quotePricing(input: PricingInput): PricingResult {
   const bundleWeights = deliveryBundles.map((bundle, index) =>
     Math.max(0, bundle.fee + bundle.remoteSurcharge - (bundles[index]?.couponDiscount ?? 0)),
   );
-  const points = pointUseOf(input.points ?? null, {
-    productPaid: productWeights.reduce((sum, w) => sum + w, 0),
-    deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
-    total: beforePoints,
-  });
+  const points = pointUseOf(
+    input.points ?? null,
+    {
+      productPaid: productWeights.reduce((sum, w) => sum + w, 0),
+      deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
+      total: beforePoints,
+    },
+    rules,
+  );
   if (points.amount > 0) {
     const productPaid = productWeights.reduce((sum, w) => sum + w, 0);
     const toLines = Math.min(points.amount, productPaid);
@@ -670,6 +688,7 @@ export function quotePricing(input: PricingInput): PricingResult {
 export function pointUseOf(
   points: PricingPoints | null,
   amounts: { productPaid: number; deliveryPaid: number; total: number },
+  moneyRules: MoneyRules = KRW_MONEY_RULES,
 ): {
   amount: number;
   maxUsable: number;
@@ -690,8 +709,8 @@ export function pointUseOf(
     if (total > 0 && cap >= total) return { amount: total, adjusted: false };
     const amount = floorUnit(Math.min(cap, total));
     const remaining = total - amount;
-    if (remaining > 0 && remaining < MIN_PAYMENT_AMOUNT) {
-      return { amount: floorUnit(total - MIN_PAYMENT_AMOUNT), adjusted: true };
+    if (remaining > 0 && remaining < moneyRules.minPayment) {
+      return { amount: floorUnit(total - moneyRules.minPayment), adjusted: true };
     }
     return { amount, adjusted: false };
   };

package/src/schemas/refund-policy.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BASE_CURRENCY, currencyCodeSchema } from "./currency";
 
 /**
  * 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
@@ -28,8 +29,26 @@ const descriptions = {
   couponShortfallCharge:
     "쿠폰 조건 미달 차감. 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. " +
     "판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true",
+  currencies:
+    "외화별 반품 배송비·교환 배송비(이슈 #130). 키는 판매 통화 코드이고 기본 통화(KRW)는 넣지 않는다. 금액은 그 통화의 최소 단위다. " +
+    "상품이 정한 통화 값이 상점 값보다 앞선다. 정하지 않은 외화로는 배송 상품을 팔지 않는다. 주면 맵 전체를 바꾼다",
 } as const;
 
+/** 외화 한 통화의 반품·교환 배송비 */
+export const currencyRefundFeesSchema = z.strictObject({
+  returnDeliveryFee: z.number().int().min(0).describe("이 통화의 반품 배송비. 통화의 최소 단위"),
+  exchangeDeliveryFee: z.number().int().min(0).describe("이 통화의 교환 배송비. 통화의 최소 단위"),
+});
+
+export type CurrencyRefundFees = z.infer<typeof currencyRefundFeesSchema>;
+
+const currencyRefundMapSchema = z
+  .partialRecord(currencyCodeSchema, currencyRefundFeesSchema)
+  .refine((map) => !(BASE_CURRENCY in map), {
+    message: "기본 통화는 currencies에 넣지 않습니다",
+  })
+  .describe(descriptions.currencies);
+
 /** 유효 환불 정책 — 상점 기본 + 상품별 덮어쓰기를 합친 결과 */
 export const refundPolicySchema = z.object({
   preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions.preShipmentDeliveryFeeRefund),
@@ -44,6 +63,7 @@ export const refundPolicySchema = z.object({
     .describe(
       `${descriptions.couponShortfallCharge}. 이 필드가 없는 이전 서버 응답은 true로 읽는다`,
     ),
+  currencies: currencyRefundMapSchema.optional(),
 });
 
 export type RefundPolicy = z.infer<typeof refundPolicySchema>;
@@ -87,6 +107,7 @@ export const refundPolicyPatchSchema = z.strictObject({
     .optional()
     .describe(descriptions.conditionalFreeShortfallCharge),
   couponShortfallCharge: z.boolean().optional().describe(descriptions.couponShortfallCharge),
+  currencies: currencyRefundMapSchema.optional(),
 });
 
 export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
@@ -114,9 +135,41 @@ export interface RefundPolicyProductInput {
 export function resolveRefundPolicy(
   storePolicy?: RefundPolicyPatch | null,
   product?: RefundPolicyProductInput | null,
-): RefundPolicy {
+): RefundPolicy;
+/**
+ * 통화의 유효 정책(이슈 #130) — 기본 통화는 위와 같다. 외화는 반품·교환 배송비를 상품 `currencies[통화]` → 상점 `currencies[통화]` 순으로 찾고
+ * (부담 규칙 boolean은 통화와 무관하다), 둘 다 없으면 null이다 — 그 통화로 배송 상품을 팔지 않는다(`NO_REFUND_FEE`).
+ * 결과의 `currencies`는 지우고 금액 필드가 그 통화 값이다. 통화별 반품비 해석은 이 함수 하나다
+ */
+export function resolveRefundPolicy(
+  storePolicy: RefundPolicyPatch | null | undefined,
+  product: RefundPolicyProductInput | null | undefined,
+  currency: string,
+): RefundPolicy | null;
+export function resolveRefundPolicy(
+  storePolicy?: RefundPolicyPatch | null,
+  product?: RefundPolicyProductInput | null,
+  currency: string = BASE_CURRENCY,
+): RefundPolicy | null {
   const store = { ...REFUND_POLICY_DEFAULTS, ...dropUndefined(storePolicy) };
-  return { ...store, ...(productRefundPolicyOverride(product) ?? {}) };
+  const override = productRefundPolicyOverride(product) ?? {};
+  const merged: RefundPolicy = { ...store, ...override };
+  if (currency === BASE_CURRENCY) {
+    // 상품 덮어쓰기의 currencies가 상점 맵을 통째로 덮지 않게 통화마다 합친다
+    if (store.currencies || override.currencies) {
+      merged.currencies = { ...store.currencies, ...override.currencies };
+    }
+    return merged;
+  }
+  const code = currency as keyof NonNullable<RefundPolicy["currencies"]>;
+  const fees = override.currencies?.[code] ?? store.currencies?.[code];
+  if (!fees) return null;
+  const { currencies: _byCurrency, ...rest } = merged;
+  return {
+    ...rest,
+    returnDeliveryFee: fees.returnDeliveryFee,
+    exchangeDeliveryFee: fees.exchangeDeliveryFee,
+  };
 }
 
 /**

package/src/schemas/scope-descriptions.ts

@@ -21,6 +21,10 @@ export const SCOPE_DESCRIPTIONS: Record<StoreScopeResource, { r: string; rw: str
   promotion: { r: "쿠폰·적립금 설정을 읽습니다", rw: "쿠폰을 발급하고 적립금을 지급합니다" },
   storefront: { r: "스토어프론트 설정을 읽습니다", rw: "스토어프론트를 편집하고 발행합니다" },
   flow: { r: "주문 흐름 설정을 읽습니다", rw: "주문 흐름을 만들고 수정합니다" },
+  inventory: {
+    r: "위치별 재고와 재고 변동 내역을 읽습니다",
+    rw: "재고를 조정·실사하고 위치 사이에서 이동합니다",
+  },
 };
 
 /** `{resource}:{r|rw}` → 문장. 카탈로그에 없는 스코프는 null */

package/src/schemas/scope.ts

@@ -33,6 +33,8 @@ export const STORE_SCOPE_RESOURCES = {
   storefront: ["r", "rw"],
   // 커머스 플로우 정의·할당(이슈 #115) — 주문 처리 행동은 order 스코프다
   flow: ["r", "rw"],
+  // 위치별 재고·재고 조정·이동·변동 내역(이슈 #132) — 기존 재고 표면(조합 재고 수정, 상품·옵션의 `stockQuantity`)은 product 스코프다
+  inventory: ["r", "rw"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -71,6 +73,7 @@ export const STORE_ROLE_SCOPES = {
     "promotion:rw",
     "storefront:rw",
     "flow:rw",
+    "inventory:rw",
   ],
   ADMIN: [
     "product:rw",
@@ -88,6 +91,7 @@ export const STORE_ROLE_SCOPES = {
     "promotion:rw",
     "storefront:rw",
     "flow:rw",
+    "inventory:rw",
   ],
   STAFF: [
     "product:rw",
@@ -99,5 +103,6 @@ export const STORE_ROLE_SCOPES = {
     "customer:r",
     "promotion:r",
     "flow:r",
+    "inventory:rw",
   ],
 } as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/shipping-policy.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { BASE_CURRENCY, currencyCodeSchema } from "./currency";
 import { type DeliveryType, type FulfillmentType, requiresShipping } from "./fulfillment";
 
 /**
@@ -32,14 +33,38 @@ const descriptions = {
     "null이면 전체 무료배송을 쓰지 않는다(상품별 조건부 무료는 그대로 동작한다). 기본 null",
   jejuSurcharge: "제주 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
   isolatedSurcharge: "도서산간 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
+  currencies:
+    "외화별 기본 배송비·전체 무료배송 기준액(이슈 #130). 키는 판매 통화 코드이고 기본 통화(KRW)는 넣지 않는다. 금액은 그 통화의 최소 단위다. " +
+    "정하지 않은 외화로는 배송 상품을 팔지 않는다. 지역 추가 배송비는 국내(기본 통화) 값만 있다. 주면 맵 전체를 바꾼다",
 } as const;
 
+/** 외화 한 통화의 상점 배송 값 */
+export const currencyShippingPolicySchema = z.strictObject({
+  baseDeliveryFee: z.number().int().min(0).describe("이 통화의 기본 배송비. 통화의 최소 단위"),
+  freeThreshold: z
+    .number()
+    .int()
+    .min(1)
+    .nullable()
+    .describe("이 통화의 전체 무료배송 기준액. null이면 쓰지 않는다"),
+});
+
+export type CurrencyShippingPolicy = z.infer<typeof currencyShippingPolicySchema>;
+
+const currencyShippingMapSchema = z
+  .partialRecord(currencyCodeSchema, currencyShippingPolicySchema)
+  .refine((map) => !(BASE_CURRENCY in map), {
+    message: "기본 통화는 currencies에 넣지 않습니다",
+  })
+  .describe(descriptions.currencies);
+
 /** 유효 배송비 정책 — 상점이 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
 export const shippingPolicySchema = z.object({
   baseDeliveryFee: z.number().int().min(0).describe(descriptions.baseDeliveryFee),
   freeThreshold: z.number().int().min(1).nullable().describe(descriptions.freeThreshold),
   jejuSurcharge: z.number().int().min(0).describe(descriptions.jejuSurcharge),
   isolatedSurcharge: z.number().int().min(0).describe(descriptions.isolatedSurcharge),
+  currencies: currencyShippingMapSchema.optional(),
 });
 
 export type ShippingPolicy = z.infer<typeof shippingPolicySchema>;
@@ -68,17 +93,41 @@ export const shippingPolicyPatchSchema = z.strictObject({
   freeThreshold: z.number().int().min(1).nullable().optional().describe(descriptions.freeThreshold),
   jejuSurcharge: z.number().int().min(0).optional().describe(descriptions.jejuSurcharge),
   isolatedSurcharge: z.number().int().min(0).optional().describe(descriptions.isolatedSurcharge),
+  currencies: currencyShippingMapSchema.optional(),
 });
 
 export type ShippingPolicyPatch = z.infer<typeof shippingPolicyPatchSchema>;
 
-/** 유효 정책 해석 — 상점이 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
-export function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy {
-  if (!patch) return { ...SHIPPING_POLICY_DEFAULTS };
-  const given = Object.fromEntries(
-    Object.entries(patch).filter(([, value]) => value !== undefined),
-  ) as ShippingPolicyPatch;
-  return { ...SHIPPING_POLICY_DEFAULTS, ...given };
+/**
+ * 유효 정책 해석 — 상점이 정한 항목 + `SHIPPING_POLICY_DEFAULTS`.
+ *
+ * `currency`(이슈 #130)를 주면 그 통화의 정책이다. 기본 통화는 지금과 같고, 외화는 `currencies[통화]`의 기본 배송비·무료 기준액에
+ * 지역 추가 배송비 0이다(할증 구간은 국내 값). 외화 값이 없으면 null — 그 통화로 배송 상품을 팔지 않는다. 통화별 값 해석은 이 함수 하나다.
+ */
+export function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy;
+export function resolveShippingPolicy(
+  patch: ShippingPolicyPatch | null | undefined,
+  currency: string,
+): ShippingPolicy | null;
+export function resolveShippingPolicy(
+  patch?: ShippingPolicyPatch | null,
+  currency: string = BASE_CURRENCY,
+): ShippingPolicy | null {
+  const given = patch
+    ? (Object.fromEntries(
+        Object.entries(patch).filter(([, value]) => value !== undefined),
+      ) as ShippingPolicyPatch)
+    : {};
+  const base: ShippingPolicy = { ...SHIPPING_POLICY_DEFAULTS, ...given };
+  if (currency === BASE_CURRENCY) return base;
+  const foreign = base.currencies?.[currency as keyof typeof base.currencies];
+  if (!foreign) return null;
+  return {
+    baseDeliveryFee: foreign.baseDeliveryFee,
+    freeThreshold: foreign.freeThreshold,
+    jejuSurcharge: 0,
+    isolatedSurcharge: 0,
+  };
 }
 
 // ─── 지역 추가 배송비 ─────────────────────────────────────

package/src/schemas/store.ts

@@ -461,6 +461,13 @@ export const sellerAddressSchema = z.object({
   zipCode: z.string(),
   address1: z.string(),
   address2: z.string().optional(),
+  inventoryLocationId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "이 주소의 재고 위치 ID — 출고지면 배송 주문을 이 위치 재고로 팔고, 반품지면 반품을 이 위치로 들인다. 위치를 하나만 쓰는 상점은 기본 위치다",
+    ),
   createdAt: z.string(),
 });
 
@@ -474,6 +481,11 @@ export const sellerAddressRequestSchema = z.object({
   zipCode: z.string().regex(/^[0-9]{5}$/),
   address1: z.string().min(1),
   address2: z.string().optional(),
+  inventoryLocationId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("재고 위치 ID. 등록에서 생략하면 기본 위치, 수정에서 생략하면 지금 연결을 유지한다"),
 });
 
 export type SellerAddressRequest = z.infer<typeof sellerAddressRequestSchema>;

package/src/schemas/webhook-event.ts

@@ -50,6 +50,12 @@ export const orderWebhookEventDataSchema = z.object({
       "주문번호(이슈 #107) — 숫자 14자리. 이 필드가 없는 이전 이벤트와 번호 체계 이전 주문은 null로 읽는다",
     ),
   status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 이 이벤트의 금액은 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 이 필드가 없는 이전 이벤트는 KRW다",
+    ),
   testPayment: z
     .boolean()
     .optional()
@@ -129,6 +135,12 @@ export const orderFulfilledWebhookEventDataSchema = z.object({
       '**Deprecated** — 항상 `{ mode: "MANUAL" }`이다. 자동 제공을 없앴고(이슈 #48) store-sdk 0.19 이하 호환으로만 싣는다. 게시된 연동이 store-sdk 0.20 이상으로 넘어간 뒤 다음 릴리스에서 뺀다',
     ),
   fulfilledAt: z.string().describe("제공 시각 (ISO 8601). 주문상품의 `deliveredAt`과 같다"),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 이 이벤트의 금액은 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 이 필드가 없는 이전 이벤트는 KRW다",
+    ),
   testPayment: z
     .boolean()
     .describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다"),
@@ -204,6 +216,12 @@ export const orderCanceledWebhookEventDataSchema = z.object({
       "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
         "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
     ),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 이 이벤트의 금액은 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 이 필드가 없는 이전 이벤트는 KRW다",
+    ),
   testPayment: z
     .boolean()
     .describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다"),
@@ -292,6 +310,12 @@ export const claimWebhookEventDataSchema = z.object({
       "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
         "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
     ),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 이 이벤트의 금액은 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 이 필드가 없는 이전 이벤트는 KRW다",
+    ),
   testPayment: z
     .boolean()
     .optional()
@@ -320,11 +344,55 @@ export const productOutOfStockWebhookEventDataSchema = z.object({
   variantId: z
     .string()
     .describe("재고가 0이 된 판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z
+    .string()
+    .optional()
+    .describe(
+      "재고가 0이 된 재고 위치 ID. 품절은 위치별 가용 재고의 0 전이다. 위치를 하나만 쓰는 상점은 기본 위치다(옛 이벤트에는 없다)",
+    ),
 });
 export type ProductOutOfStockWebhookEventData = z.infer<
   typeof productOutOfStockWebhookEventDataSchema
 >;
 
+/**
+ * 위치별 재고 변화(이슈 #132) — 재고 변동 내역 한 행마다 한 건이다. 같은 위치·조합의 순서는 `levelVersion`(빈 번호 없음)으로 맞추고,
+ * 상점 전체 순서는 `movementSeq`(재고 변동 내역 조회의 `after` 커서와 같은 값)다. 자기가 한 조정의 반향은 `actorType`·`actorId`·`operationId`로 거른다.
+ * 출고 대기·실재고(상태 전이) 변화는 이벤트를 내지 않는다 — 필요하면 위치별 재고 조회를 다시 읽는다
+ */
+export const inventoryChangedWebhookEventDataSchema = z.object({
+  productId: z.string().describe("상품 ID"),
+  variantId: z
+    .string()
+    .describe("판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z.string().describe("재고 위치 ID"),
+  available: z.number().int().describe("변화 뒤 가용 재고"),
+  delta: z.number().int().describe("가용 재고 변화량(0이 아니다)"),
+  kind: z
+    .string()
+    .describe(
+      "변동 종류 — `OPENING`·`SALE`·`RESTORE`·`REVERT`·`EXCHANGE_OUT`·`ADJUST`·`COUNT`·`TRANSFER_OUT`·`TRANSFER_IN`·`REMOVED`. 값이 늘 수 있다",
+    ),
+  reason: z.string().nullable().describe("조정·실사 사유 코드. 없으면 null"),
+  levelVersion: z
+    .number()
+    .int()
+    .describe("위치별 재고 행의 버전 — 같은 위치·조합 안에서 빈 번호 없이 오른다"),
+  movementSeq: z.number().int().describe("상점별 재고 변동 내역 순번"),
+  actorType: z.string().describe("행위자 유형 — `seller`·`app`·`agent`·`system`"),
+  actorId: z.string().nullable().describe("행위자 ID. 시스템이면 null"),
+  refType: z
+    .string()
+    .nullable()
+    .describe("출처 유형 — `order_item`·`claim`·`operation`. 없으면 null"),
+  refId: z.string().nullable().describe("출처 ID"),
+  operationId: z.string().nullable().describe("재고 조정·이동 요청 ID. 조정·이동이 아니면 null"),
+  occurredAt: z.string().describe("변화 시각"),
+});
+export type InventoryChangedWebhookEventData = z.infer<
+  typeof inventoryChangedWebhookEventDataSchema
+>;
+
 export const orderWebhookEventSchema = z.object({
   ...envelopeFields,
   type: z.enum([
@@ -380,6 +448,12 @@ export const productOutOfStockWebhookEventSchema = z.object({
   data: productOutOfStockWebhookEventDataSchema,
 });
 
+export const inventoryChangedWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("INVENTORY.CHANGED"),
+  data: inventoryChangedWebhookEventDataSchema,
+});
+
 /**
  * 플로우 알림(이슈 #115) — 상점이 플로우에 둔 알림 블록(`core.notify`, 채널 `webhook`)이 보낸다. 구매자 알림(알림톡·메일)은 이 이벤트를 받아
  * 상점이 보낸다(플랫폼은 구매자에게 직접 보내지 않는다). 개인정보는 싣지 않는다
@@ -436,6 +510,7 @@ export const webhookEventSchema = z
     productOutOfStockWebhookEventSchema,
     flowNotificationWebhookEventSchema,
     flowStateChangedWebhookEventSchema,
+    inventoryChangedWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",