@sayren/store-sdk 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.31.0",
+  "version": "0.33.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,
@@ -171,6 +187,13 @@ import {
   type UpdateLoginSettingsRequest,
   updateLoginSettingsRequestSchema,
 } from "./schemas/login";
+import {
+  type CreateMarketRequestInput,
+  createMarketRequestSchema,
+  marketSchema,
+  type UpdateMarketRequestInput,
+  updateMarketRequestSchema,
+} from "./schemas/market";
 import {
   type CustomerInquiryCategory,
   inquirySchema,
@@ -238,12 +261,14 @@ import {
   type UpdatePaymentSettingsRequest,
   type UpsertKakaoPayProviderRequest,
   type UpsertNaverPayProviderRequest,
+  type UpsertPayPalProviderRequest,
   type UpsertPortOneProviderRequest,
   type UpsertTossPaymentsProviderRequest,
   updatePaymentProviderRequestSchema,
   updatePaymentSettingsRequestSchema,
   upsertKakaoPayProviderRequestSchema,
   upsertNaverPayProviderRequestSchema,
+  upsertPayPalProviderRequestSchema,
   upsertPortOneProviderRequestSchema,
   upsertTossPaymentsProviderRequestSchema,
   type VerifyPaymentProviderRequest,
@@ -1049,11 +1074,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, {
@@ -1418,6 +1458,14 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("PUT", "/store/payment-providers/naverpay", paymentProviderSchema, {
           body: upsertNaverPayProviderRequestSchema.parse(body),
         }),
+      /**
+       * `PUT /v1/store/payment-providers/paypal` — PayPal(직접 연동) 자격 증명 세트 저장. 규칙·에러는 `upsertTossPayments`와 같다
+       * (가맹점 식별자는 `clientId`, 비밀 필드는 `clientSecret`). 결제 옵션은 PayPal 간편결제 하나이고 `currencies`의 외화 주문서에만 나온다.
+       */
+      upsertPayPal: (body: UpsertPayPalProviderRequest) =>
+        storeHttp.request("PUT", "/store/payment-providers/paypal", paymentProviderSchema, {
+          body: upsertPayPalProviderRequestSchema.parse(body),
+        }),
       /**
        * `PATCH /v1/store/payment-providers/{provider}` — 사용 여부(`enabled`)·샌드박스 스위치(`sandboxMode`) 변경.
        * 하나 이상 보내야 한다(아니면 요청 전에 ZodError). 검증을 모두 통과해야 한 번에 적용된다(부분 적용 없음).
@@ -1752,6 +1800,65 @@ 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),
+        }),
+    },
+
+    /** 판매 권역(이슈 #130) — 국가·통화·도메인. 쓰기는 다중 통화가 켜진 상점에서만 된다 */
+    markets: {
+      list: () => storeHttp.request("GET", "/markets", z.array(marketSchema)),
+      get: (marketId: string) => storeHttp.request("GET", path`/markets/${marketId}`, marketSchema),
+      create: (body: CreateMarketRequestInput) =>
+        storeHttp.request("POST", "/markets", marketSchema, {
+          body: createMarketRequestSchema.parse(body),
+        }),
+      update: (marketId: string, body: UpdateMarketRequestInput) =>
+        storeHttp.request("PATCH", path`/markets/${marketId}`, marketSchema, {
+          body: updateMarketRequestSchema.parse(body),
+        }),
+      archive: (marketId: string) => storeHttp.requestVoid("DELETE", path`/markets/${marketId}`),
+    },
+
     pickupLocations: {
       list: () => storeHttp.request("GET", "/pickup-locations", z.array(pickupLocationSchema)),
       create: (body: PickupLocationRequestInput) =>

package/src/index.ts

@@ -30,10 +30,14 @@ export * from "./schemas/commerce-flow";
 export * from "./schemas/commerce-number";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
+export * from "./schemas/currency";
+export * from "./schemas/currency-prices";
 export * from "./schemas/customer";
 export * from "./schemas/customer-delegation";
 export * from "./schemas/fulfillment";
+export * from "./schemas/inventory";
 export * from "./schemas/login";
+export * from "./schemas/market";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";

package/src/schemas/analytics.ts

@@ -100,6 +100,22 @@ export const analyticsOverviewSchema = z.object({
     .number()
     .int()
     .describe("집계에서 뺀 봇 세션 수 — 봇 표시 이벤트가 하나라도 있는 세션은 모든 값에서 빠진다"),
+  byCurrency: z
+    .array(
+      z.object({
+        currency: z.string().describe("구매 통화(ISO 4217)"),
+        purchases: z.number().int().describe("실결제 구매 수(테스트 결제 제외)"),
+        revenue: z
+          .number()
+          .int()
+          .describe("매출(그 통화의 최소 단위). `includeTest`면 테스트 결제 매출을 더한다"),
+      }),
+    )
+    .optional()
+    .default([])
+    .describe(
+      "통화별 매출(이슈 #130) — 기간 합계, 기본 통화(KRW) 포함. 통화 사이는 환산하지 않는다. `summary.revenue`는 기본 통화 매출이다. 옛 서버 응답은 빈 목록",
+    ),
 });
 export type AnalyticsOverview = z.infer<typeof analyticsOverviewSchema>;
 

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/coupon.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { pageQueryShape } from "./common";
+import { currencyCodeSchema } from "./currency";
 import {
   COUPON_CONDITIONS_DEFAULTS,
   COUPON_TARGET_LIST_MAX,
@@ -111,6 +112,11 @@ export const createCouponRequestSchema = z
     totalUseLimit: limitField(descriptions.totalUseLimit),
     perMemberIssueLimit: limitField(descriptions.perMemberIssueLimit),
     perMemberUseLimit: limitField(descriptions.perMemberUseLimit),
+    currency: currencyCodeSchema
+      .optional()
+      .describe(
+        "쿠폰 통화(이슈 #130). 정액·최대 할인액·최소 주문 금액이 이 통화 값이고 같은 통화 주문서에만 적용된다. 생략하면 기본 통화(KRW). 판매 통화여야 하고 만든 뒤에는 바꿀 수 없다",
+      ),
   })
   .superRefine((body, ctx) => {
     const issue = (path: string, message: string) =>
@@ -197,6 +203,13 @@ export const couponSchema = z.object({
     .describe("발급 수 — 회수한 발급도 센다. 총 발급 한도(`totalIssueLimit`)가 이 값과 비교된다"),
   reservedCount: z.number().int().describe("결제 중인 예약 수 — 결제가 끝나거나 만료되면 풀린다"),
   usedCount: z.number().int().describe("사용 수 — 전량 취소로 복원되면 줄어든다"),
+  currency: z
+    .string()
+    .optional()
+    .default("KRW")
+    .describe(
+      "쿠폰 통화(이슈 #130). 금액 필드는 이 통화의 최소 단위다. 옛 서버 응답은 KRW로 읽는다",
+    ),
   status: couponStatusSchema,
   locked: z.boolean().describe("발급·사용이 시작돼 혜택·조건·대상·사용 시작일을 바꿀 수 없는가"),
   lockedAt: z.string().nullable(),

package/src/schemas/currency-prices.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { BASE_CURRENCY, currencyCodeSchema, isSaleUnitPrice } from "./currency";
+
+/**
+ * 통화별 가격 입력·응답 (이슈 #130 설계 D3·D6·§8.1) — **외화만 담는다.** 기본 통화(KRW) 값은 지금의 평면 필드(`salePrice`·`deliveryFee` 등)다.
+ * 금액은 그 통화의 최소 단위 정수다. 목록에 없는 외화로는 그 상품을 팔지 않는다. 쓰기(PUT·POST)는 목록 전체 교체이고 생략하면 유지한다.
+ * 통화는 상점의 판매 통화여야 한다(400 `CURRENCY_NOT_SOLD`).
+ */
+
+/** 외화만·통화마다 한 번 — 기본 통화 원소와 같은 통화 두 번은 400이다 */
+function foreignOnce<T extends { currency: string }>(items: readonly T[], ctx: z.RefinementCtx) {
+  const seen = new Set<string>();
+  items.forEach((item, index) => {
+    if (item.currency === BASE_CURRENCY) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "currency"],
+        message: "기본 통화는 prices에 넣지 않습니다",
+      });
+    }
+    if (seen.has(item.currency)) {
+      ctx.addIssue({ code: "custom", path: [index, "currency"], message: "통화가 겹칩니다" });
+    }
+    seen.add(item.currency);
+  });
+}
+
+/** 상품 판매가의 외화 값 */
+export const productCurrencyPriceSchema = z
+  .strictObject({
+    currency: currencyCodeSchema,
+    salePrice: z
+      .number()
+      .int()
+      .describe(
+        "이 통화의 판매가. 통화의 최소 단위이고 판매가 단위(KRW 10, JPY 1, USD 1센트, TWD 100)의 배수다",
+      ),
+    originalPrice: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .optional()
+      .describe("이 통화의 정가(표시용). 생략은 null"),
+    discountAmount: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .optional()
+      .describe(
+        "정액 즉시할인의 이 통화 값. 정률 할인은 모든 통화에 그대로 적용된다. null이면 이 통화에는 정액 할인이 없다",
+      ),
+  })
+  .superRefine((value, ctx) => {
+    if (!isSaleUnitPrice(value.salePrice, value.currency)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["salePrice"],
+        message: "판매가가 이 통화의 판매가 단위가 아닙니다 (INVALID_PRICE_UNIT)",
+      });
+    }
+  });
+
+export const productCurrencyPricesSchema = z
+  .array(productCurrencyPriceSchema)
+  .max(15)
+  .superRefine(foreignOnce)
+  .describe(
+    "외화 판매가(이슈 #130). 기본 통화는 넣지 않는다. 주면 판매 중인 외화 안에서 목록 전체를 바꾸고(판매하지 않는 통화의 저장 값은 유지한다) 생략하면 유지한다. 목록에 없는 외화로는 팔지 않는다",
+  );
+
+export type ProductCurrencyPrice = z.infer<typeof productCurrencyPriceSchema>;
+
+/** 상품 배송의 외화 값 — 배송비 유형·출고지는 상품 하나다 */
+export const shippingCurrencyPriceSchema = z.strictObject({
+  currency: currencyCodeSchema,
+  deliveryFee: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      "이 통화의 배송비. 생략하면 그 통화의 상점 기본 배송비이고, 상점 값도 없으면 이 통화로 배송 상품을 팔지 않는다. FREE면 0",
+    ),
+  conditionalFreeAmount: z
+    .number()
+    .int()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe("이 통화의 조건부 무료 기준 묶음 소계. CONDITIONAL_FREE가 아니면 무시한다"),
+});
+
+export const shippingCurrencyPricesSchema = z
+  .array(shippingCurrencyPriceSchema)
+  .max(15)
+  .superRefine(foreignOnce)
+  .describe(
+    "외화 배송비(이슈 #130). 기본 통화는 넣지 않는다. 주면 판매 중인 외화 안에서 목록 전체를 바꾸고(판매하지 않는 통화의 저장 값은 유지한다) 생략하면 유지한다",
+  );
+
+/** 저장된 외화 배송 값(응답) */
+export const storedShippingCurrencyPriceSchema = z.object({
+  currency: z.string(),
+  deliveryFee: z.number().int(),
+  conditionalFreeAmount: z.number().int().nullable(),
+});
+
+/** 저장된 외화 판매가(응답) */
+export const storedProductCurrencyPriceSchema = z.object({
+  currency: z.string(),
+  salePrice: z.number().int(),
+  originalPrice: z.number().int().nullable(),
+  discountAmount: z.number().int().nullable(),
+});
+
+/** 조합·추가 선택 값 추가금의 외화 값 — 추가금은 판매가 단위 규칙이 없다(설계 D4) */
+export const additionalCurrencyPriceSchema = z.strictObject({
+  currency: currencyCodeSchema,
+  additionalPrice: z.number().int().min(0).describe("이 통화의 추가금. 통화의 최소 단위(0 이상)"),
+});
+
+export const additionalCurrencyPricesSchema = z
+  .array(additionalCurrencyPriceSchema)
+  .max(15)
+  .superRefine(foreignOnce)
+  .describe(
+    "외화 추가금(이슈 #130). 기본 통화는 넣지 않는다. 주면 판매 중인 외화 안에서 목록 전체를 바꾸고(판매하지 않는 통화의 저장 값은 유지한다) 생략하면 유지한다. 기본 통화 추가금이 0이 아닌데 목록에 없는 외화로는 이 조합·값을 팔지 않는다",
+  );
+
+export type AdditionalCurrencyPrice = z.infer<typeof additionalCurrencyPriceSchema>;
+
+/** 저장된 외화 추가금(응답) */
+export const storedAdditionalCurrencyPriceSchema = z.object({
+  currency: z.string(),
+  additionalPrice: z.number().int(),
+});

package/src/schemas/currency.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+
+/**
+ * 통화표와 금액 변환(이슈 #130). 숫자만 다룬다 — 사람이 읽는 문자열(「1,000원」·「$10.99」)은 각 앱의 `formatMoney`가 만든다.
+ *
+ * 모든 금액은 통화의 **최소 단위 정수**다(KRW 1원, USD 1센트, JPY 1엔). 주 단위(10.99달러)는 표시·입력·PG 요청 형식에만 쓴다.
+ * storefront-sdk `schemas/currency.ts`는 이 파일의 사본이다(storefront-sdk는 store-sdk에 의존하지 않는다). api 유닛 테스트가 두 표가 같은지 고정한다.
+ * 고치면 사본도 같이 고친다.
+ */
+
+export interface CurrencySpec {
+  /** ISO 4217 코드 */
+  code: string;
+  /** 소수 자릿수(ISO 4217) — 주 단위 1 = 최소 단위 10^digits */
+  digits: number;
+  /** 판매가 단위(최소 단위). 판매가는 이 값의 배수이고 최소값도 이 값이다. 추가금에는 적용하지 않는다 */
+  saleUnit: number;
+  /** 통화표 최소 결제액(최소 단위). 실제 하한은 PG 하한과의 큰 값이다(`minPaymentOf`) */
+  minPayment: number;
+  /** 주문 최대 금액(최소 단위). int4와 PG 상한 중 작은 쪽 */
+  maxOrderAmount: number;
+}
+
+const INT4_MAX = 2_147_483_647;
+/** Stripe 카드 외 결제 상한이 8자리(999,999.99)라 2자리 통화는 이 값이 int4보다 먼저 걸린다 */
+const PG_8_DIGIT_MAX = 99_999_999;
+
+/**
+ * 1차 판매 통화 16종(설계 Q6). 판매가 단위는 KRW 10원(현행 규칙), JPY 1엔, 2자리 통화 1센트, TWD 100(= 1달러, PayPal이 TWD를 정수로만 받는다).
+ * 최소 결제액은 KRW가 현행 100원이고, 그 밖은 Stripe 최소 청구액(https://docs.stripe.com/currencies#minimum-and-maximum-charge-amounts)을 따른다.
+ * Stripe 표에 없는 CNY·TWD·PHP는 USD 0.50 근처의 근사값이다(PG 하한은 어댑터 선언이 따로 더한다).
+ */
+export const CURRENCIES = {
+  KRW: { code: "KRW", digits: 0, saleUnit: 10, minPayment: 100, maxOrderAmount: INT4_MAX },
+  USD: { code: "USD", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  EUR: { code: "EUR", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  JPY: { code: "JPY", digits: 0, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  GBP: { code: "GBP", digits: 2, saleUnit: 1, minPayment: 30, maxOrderAmount: PG_8_DIGIT_MAX },
+  CNY: { code: "CNY", digits: 2, saleUnit: 1, minPayment: 400, maxOrderAmount: PG_8_DIGIT_MAX },
+  HKD: { code: "HKD", digits: 2, saleUnit: 1, minPayment: 400, maxOrderAmount: PG_8_DIGIT_MAX },
+  TWD: { code: "TWD", digits: 2, saleUnit: 100, minPayment: 2_000, maxOrderAmount: PG_8_DIGIT_MAX },
+  SGD: { code: "SGD", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  AUD: { code: "AUD", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  CAD: { code: "CAD", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  THB: { code: "THB", digits: 2, saleUnit: 1, minPayment: 1_000, maxOrderAmount: PG_8_DIGIT_MAX },
+  MYR: { code: "MYR", digits: 2, saleUnit: 1, minPayment: 200, maxOrderAmount: PG_8_DIGIT_MAX },
+  PHP: { code: "PHP", digits: 2, saleUnit: 1, minPayment: 3_000, maxOrderAmount: PG_8_DIGIT_MAX },
+  NZD: { code: "NZD", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+  CHF: { code: "CHF", digits: 2, saleUnit: 1, minPayment: 50, maxOrderAmount: PG_8_DIGIT_MAX },
+} as const satisfies Record<string, CurrencySpec>;
+
+export type CurrencyCode = keyof typeof CURRENCIES;
+
+export const CURRENCY_CODES = Object.keys(CURRENCIES) as [CurrencyCode, ...CurrencyCode[]];
+
+/** 기본 통화 — 1차는 KRW 고정(설계 Q9). 기본 권역의 통화이고 지금의 금액 컬럼이 이 통화 값이다 */
+export const BASE_CURRENCY = "KRW" satisfies CurrencyCode;
+
+export const currencyCodeSchema = z
+  .enum(CURRENCY_CODES)
+  .describe("통화(ISO 4217). 금액 필드는 이 통화의 최소 단위 정수다");
+
+export function isCurrencyCode(value: string): value is CurrencyCode {
+  return Object.hasOwn(CURRENCIES, value);
+}
+
+/** 통화표 항목. 모르는 통화면 RangeError — 판매 통화가 아닌 값이 계산까지 오면 원천의 검증 누락이다 */
+export function currencySpecOf(code: string): CurrencySpec {
+  if (!isCurrencyCode(code)) throw new RangeError(`unsupported currency: ${code}`);
+  return CURRENCIES[code];
+}
+
+function scaleOf(spec: CurrencySpec): number {
+  return 10 ** spec.digits;
+}
+
+/** 주 단위 → 최소 단위(반올림). 입력·화면 값 변환용이고 PG 응답 해석은 `fromDecimalString`이다 */
+export function toMinor(major: number, currency: string): number {
+  return Math.round(major * scaleOf(currencySpecOf(currency)));
+}
+
+/** 최소 단위 → 주 단위(표시용 숫자) */
+export function minorToMajor(minor: number, currency: string): number {
+  return minor / scaleOf(currencySpecOf(currency));
+}
+
+/** 최소 단위 → PG 요청 형식 십진 문자열(`1099` USD → `"10.99"`, `1000` KRW → `"1000"`). 정수 연산만 쓴다 */
+export function toDecimalString(minor: number, currency: string): string {
+  if (!Number.isSafeInteger(minor)) throw new RangeError(`amount must be an integer: ${minor}`);
+  const { digits } = currencySpecOf(currency);
+  const sign = minor < 0 ? "-" : "";
+  const abs = String(Math.abs(minor));
+  if (digits === 0) return `${sign}${abs}`;
+  const padded = abs.padStart(digits + 1, "0");
+  return `${sign}${padded.slice(0, -digits)}.${padded.slice(-digits)}`;
+}
+
+/**
+ * PG 응답의 십진 문자열 → 최소 단위 정수. 통화 자릿수보다 긴 소수는 끝이 0일 때만 받는다(`"10.990"` → 1099, `"10.999"`는 RangeError).
+ * 형식이 틀리면 RangeError다 — 금액을 추정하지 않는다.
+ */
+export function fromDecimalString(value: string, currency: string): number {
+  const { digits } = currencySpecOf(currency);
+  const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(value.trim());
+  if (!match) throw new RangeError(`invalid decimal amount: ${value}`);
+  const [, sign, whole, fraction = ""] = match;
+  const extra = fraction.slice(digits);
+  if (/[^0]/.test(extra))
+    throw new RangeError(`too many fraction digits for ${currency}: ${value}`);
+  const minor = Number(`${whole}${fraction.slice(0, digits).padEnd(digits, "0")}`);
+  if (!Number.isSafeInteger(minor)) throw new RangeError(`amount out of range: ${value}`);
+  return sign === "-" && minor !== 0 ? -minor : minor;
+}
+
+/** 판매가 단위로 내림 — 할인·정률 쿠폰 계산의 단위 맞춤(KRW 10원 내림은 현행 규칙 그대로) */
+export function floorToSaleUnit(amount: number, currency: string): number {
+  const { saleUnit } = currencySpecOf(currency);
+  return Math.floor(amount / saleUnit) * saleUnit;
+}
+
+/** 판매가 규칙(판매가 단위의 배수, 최소 판매가 단위)을 지키는가 */
+export function isSaleUnitPrice(amount: number, currency: string): boolean {
+  const { saleUnit } = currencySpecOf(currency);
+  return Number.isInteger(amount) && amount >= saleUnit && amount % saleUnit === 0;
+}
+
+/** 판매가 규칙 위반 — api가 400 `INVALID_PRICE_UNIT`으로 바꾼다 */
+export class InvalidPriceUnitError extends Error {
+  readonly code = "INVALID_PRICE_UNIT";
+  constructor(
+    readonly amount: number,
+    readonly currency: string,
+    readonly saleUnit: number,
+  ) {
+    super(
+      `sale price ${amount} ${currency} must be a multiple of ${saleUnit} and at least ${saleUnit}`,
+    );
+    this.name = "InvalidPriceUnitError";
+  }
+}
+
+/** 판매가 단위 검증의 원천 — zod `superRefine`과 api 상품 쓰기가 같이 부른다 */
+export function assertSaleUnit(amount: number, currency: string): void {
+  if (!isSaleUnitPrice(amount, currency)) {
+    throw new InvalidPriceUnitError(amount, currency, currencySpecOf(currency).saleUnit);
+  }
+}
+
+/**
+ * 최소 결제액 = max(통화표 값, 후보들). 후보는 PG 어댑터 선언의 하한(`descriptor.minAmount(currency)`, #131)이고 null은 「하한 없음」이다.
+ * 서버의 최소 결제 검사는 이 값 하나를 쓴다.
+ */
+export function minPaymentOf(
+  currency: string,
+  candidates: ReadonlyArray<number | null | undefined> = [],
+): number {
+  let floor = currencySpecOf(currency).minPayment;
+  for (const candidate of candidates) {
+    if (candidate !== null && candidate !== undefined && candidate > floor) floor = candidate;
+  }
+  return floor;
+}
+
+/** 통화 규칙 값 — 순수 금액 함수가 상수 대신 입력으로 받는다. 생략하면 KRW 규칙이다(`KRW_MONEY_RULES`) */
+export interface MoneyRules {
+  currency: string;
+  saleUnit: number;
+  minPayment: number;
+  maxOrderAmount: number;
+}
+
+/** 통화의 규칙 값. `minPayment`를 주면(서버가 `minPaymentOf`로 구한 값) 통화표 값 대신 쓴다 */
+export function moneyRulesOf(currency: string, options: { minPayment?: number } = {}): MoneyRules {
+  const spec = currencySpecOf(currency);
+  return {
+    currency: spec.code,
+    saleUnit: spec.saleUnit,
+    minPayment: options.minPayment ?? spec.minPayment,
+    maxOrderAmount: spec.maxOrderAmount,
+  };
+}
+
+/** 기본 통화(KRW) 규칙 — 규칙 값을 넘기지 않는 옛 호출부의 기본값 */
+export const KRW_MONEY_RULES: MoneyRules = moneyRulesOf(BASE_CURRENCY);

package/src/schemas/customer.ts

@@ -28,7 +28,12 @@ export const customerListQuerySchema = z.object({
 /** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
 export const customerStatsSchema = z.object({
   orderCount: z.number().int().describe("주문 수(취소 포함)"),
-  totalPaid: z.number().int().describe("구매 금액(원) — 취소·완료된 반품 제외"),
+  totalPaid: z
+    .number()
+    .int()
+    .describe(
+      "구매 금액(원) — 취소·완료된 반품 제외. 원화 주문만 더한다(외화 주문은 환산하지 않고 빠진다)",
+    ),
   lastOrderedAt: z.string().nullable().describe("최근 주문 시각"),
 });
 
@@ -56,6 +61,20 @@ export const customerAddressSchema = z.object({
   zipCode: z.string(),
   address1: z.string(),
   address2: z.string().nullable(),
+  countryCode: z
+    .string()
+    .optional()
+    .default("KR")
+    .describe(
+      "국가(ISO 3166-1 alpha-2, 이슈 #130). 해외 주소의 `zipCode`는 그 나라 우편번호이고 없으면 빈 문자열이다",
+    ),
+  city: z.string().nullable().optional().default(null).describe("해외 주소의 도시. 국내는 null"),
+  region: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("해외 주소의 주·도·현. 국내는 null"),
 });
 
 // ── 동의 이력 (이슈 #26) ────────────────────────────────────

package/src/schemas/fulfillment.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { shippingCurrencyPricesSchema, storedShippingCurrencyPriceSchema } from "./currency-prices";
 
 /**
  * 상품 유형 (이슈 #48·#57) — 배송이 필요한 상품과 필요 없는 상품을 가르는 축이다.
@@ -271,6 +272,7 @@ const shippingCreateSchema = z
       .describe("무료 배송이 되는 묶음 소계. 원 단위. CONDITIONAL_FREE에서만 받고 필수다"),
     shippingAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
     returnAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.return),
+    prices: shippingCurrencyPricesSchema.optional(),
   })
   .superRefine(refineShippingConsistency);
 
@@ -304,6 +306,7 @@ const shippingUpdateSchema = z
       .describe("무료 배송이 되는 묶음 소계. CONDITIONAL_FREE면 필수, 아니면 null"),
     shippingAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
     returnAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.return),
+    prices: shippingCurrencyPricesSchema.optional(),
   })
   .superRefine(refineShippingConsistency);
 
@@ -347,6 +350,10 @@ export const productFulfillmentSchema = z.discriminatedUnion("type", [
         .string()
         .nullable()
         .describe("반품지 주소 id. null이면 상점 기본 반품지를 따른다"),
+      prices: z
+        .array(storedShippingCurrencyPriceSchema)
+        .optional()
+        .describe("외화 배송비(이슈 #130). 관리 API 상품 조회만 싣는다"),
     }),
     methods: storedMethodsSchema,
   }),
@@ -476,6 +483,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 +501,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>;