@sayren/store-sdk 0.31.0 → 0.33.0

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { currencyCodeSchema } from "./currency";
+
+/**
+ * 판매 권역 (이슈 #130) — 상점이 어느 국가에 어느 통화로 파는지를 정한다.
+ *
+ * 권역 = 이름 + 통화 하나 + 국가 목록 + 연결 도메인 + 쿠폰·적립금 사용. 국가는 상점 안에서 한 권역에만 속하고, 판매 국가는 보관하지 않은 모든 권역 국가의
+ * 합집합이다. 기본 권역은 상점마다 하나이고 그 통화가 기본 통화(KRW)다. 기본 권역은 보관할 수 없고 국가 목록을 비울 수 없다. 권역의 통화는 만들 때만 정한다.
+ *
+ * 스토어프론트는 요청마다 도메인(`X-Storefront-Host`) → 구매자 국가(`X-Buyer-Country`) → 기본 권역 순으로 권역을 고르고, 주문서가 그 권역·통화를 굳힌다.
+ * 외화 권역은 적립금을 켤 수 없다(적립금은 기본 통화 단위다).
+ */
+
+const countryCodeSchema = z
+  .string()
+  .regex(/^[A-Za-z]{2}$/, "국가는 ISO 3166-1 alpha-2 두 글자입니다")
+  .transform((value) => value.toUpperCase())
+  .describe("국가(ISO 3166-1 alpha-2, 예: KR·US·JP)");
+
+const hostnameSchema = z
+  .string()
+  .min(1)
+  .max(253)
+  .regex(/^[A-Za-z0-9.-]+$/, "도메인은 호스트 이름만 입력합니다(예: shop.example.com)")
+  .transform((value) => value.toLowerCase().replace(/\.$/, ""))
+  .describe(
+    "연결 도메인(호스트 이름). 셀러가 직접 호스팅하는 스토어프론트가 `X-Storefront-Host`로 보낸다",
+  );
+
+export const marketSchema = z.object({
+  marketId: z.string(),
+  name: z.string(),
+  currency: currencyCodeSchema,
+  isDefault: z
+    .boolean()
+    .describe("기본 권역. 상점마다 하나이고 보관할 수 없다. 이 통화가 기본 통화다"),
+  countries: z.array(z.string()).describe("이 권역 국가. 국가는 상점 안에서 한 권역에만 속한다"),
+  domains: z.array(z.string()).describe("이 권역에 연결한 도메인"),
+  couponsEnabled: z.boolean().describe("이 권역 주문서에서 쿠폰을 쓸 수 있는가"),
+  pointsEnabled: z
+    .boolean()
+    .describe("이 권역 주문서에서 적립금을 쓸 수 있는가. 외화 권역은 늘 false다"),
+  archivedAt: z
+    .string()
+    .nullable()
+    .describe("보관 시각. 보관한 권역은 판정에서 빠지고 그 국가·도메인은 풀린다"),
+});
+
+export type Market = z.infer<typeof marketSchema>;
+
+export const createMarketRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50),
+  currency: currencyCodeSchema.describe("이 권역의 통화. 만든 뒤에는 바꿀 수 없다"),
+  countries: z.array(countryCodeSchema).min(1).max(250),
+  domains: z.array(hostnameSchema).max(20).optional(),
+  couponsEnabled: z.boolean().optional().describe("기본 false"),
+  pointsEnabled: z.boolean().optional().describe("기본 false. 외화 권역은 true로 둘 수 없다"),
+});
+
+export type CreateMarketRequest = z.infer<typeof createMarketRequestSchema>;
+export type CreateMarketRequestInput = z.input<typeof createMarketRequestSchema>;
+
+export const updateMarketRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50).optional(),
+  countries: z
+    .array(countryCodeSchema)
+    .max(250)
+    .optional()
+    .describe("주면 국가 목록 전체를 바꾼다. 다른 권역의 국가는 그 권역에서 먼저 빼야 한다"),
+  domains: z.array(hostnameSchema).max(20).optional().describe("주면 도메인 목록 전체를 바꾼다"),
+  couponsEnabled: z.boolean().optional(),
+  pointsEnabled: z.boolean().optional().describe("외화 권역은 true로 둘 수 없다"),
+});
+
+export type UpdateMarketRequest = z.infer<typeof updateMarketRequestSchema>;
+export type UpdateMarketRequestInput = z.input<typeof updateMarketRequestSchema>;

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`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",

package/src/schemas/order.ts

@@ -21,6 +21,12 @@ export const orderSummarySchema = z.object({
       "진행 중 주문상품 가운데 가장 앞 단계(취소 제외, 모두 취소면 CANCELED, #115). 섞인 주문에서 아직 기다리는 단계다. 서버는 항상 싣는다",
     ),
   orderedAt: z.string(),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 금액 필드는 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 없으면 KRW다. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -33,7 +39,10 @@ export type OrderSummary = z.infer<typeof orderSummarySchema>;
 export const shippingAddressSchema = z.object({
   receiverName: z.string(),
   phone: z.string(),
-  zipCode: z.string(),
+  zipCode: z.string().describe("우편번호. 해외 배송지는 그 나라 우편번호이고 없으면 빈 문자열이다"),
+  countryCode: z.string().optional().describe("배송 국가(이슈 #130). 없으면 국내(KR)다"),
+  region: z.string().nullish().describe("해외 배송지의 1차 행정 구역"),
+  city: z.string().nullish().describe("해외 배송지의 도시. 국내 배송지는 없다"),
   address1: z.string(),
   address2: z.string().nullish(),
   deliveryMemo: z.string().nullish(),
@@ -264,6 +273,12 @@ export const orderSchema = z.object({
         "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
       ),
   }),
+  currency: z
+    .string()
+    .optional()
+    .describe(
+      "주문 통화(ISO 4217, 이슈 #130). 금액 필드는 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 없으면 KRW다. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(

package/src/schemas/payment.ts

@@ -10,12 +10,21 @@ import { type PageParams, pageSchema } from "./common";
  */
 
 export const pgProviderSchema = z
-  .enum(["tosspayments", "portone", "kakaopay", "naverpay"])
+  .enum(["tosspayments", "portone", "kakaopay", "naverpay", "paypal"])
   .describe(
-    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동)",
+    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동), `paypal`=PayPal(직접 연동, 외화)",
   );
 export type PgProvider = z.infer<typeof pgProviderSchema>;
 
+/**
+ * 응답에 실리는 PG — 서버가 PG를 추가해도 응답 파싱이 깨지지 않게 문자열로 받는다(`easyPayProviderResponseSchema`와 같은 방식, 이슈 #131 CD2).
+ * 요청(우선순위·리포트 필터·경로)은 값을 골라 보내는 자리라 `pgProviderSchema` enum 그대로다. 현재 값은 `pgProviderSchema`의 값이고
+ * 화면은 모르는 값을 원문 그대로 보여 준다
+ */
+export const pgProviderResponseSchema = z
+  .string()
+  .describe("PG 식별자(`pgProviderSchema`의 값). 모르는 값이 와도 응답 파싱이 깨지지 않는다");
+
 /**
  * 간편결제 전용 PG — 결제수단이 간편결제 하나이고 간편결제사가 PG 자신이다(`kakaopay` → `KAKAOPAY`).
  * 이 PG는 `easyPayProviders` 설정 없이 결제 옵션이 하나(`EASY_PAY` + 그 간편결제사) 나온다
@@ -23,6 +32,7 @@ export type PgProvider = z.infer<typeof pgProviderSchema>;
 export const DEDICATED_EASY_PAY_PROVIDER = {
   kakaopay: "KAKAOPAY",
   naverpay: "NAVERPAY",
+  paypal: "PAYPAL",
 } as const satisfies Partial<Record<PgProvider, string>>;
 
 export const pgPaymentMethodSchema = z
@@ -34,7 +44,7 @@ export type PgPaymentMethod = z.infer<typeof pgPaymentMethodSchema>;
  * 간편결제사 — 결제 옵션(스토어프론트 `paymentOptions`)과 PG 설정의 `easyPayProviders`에 쓴다.
  * `@sayren/storefront-sdk`의 `easyPayProviderSchema`와 같은 값이다(api 계약 테스트가 고정한다)
  */
-export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO"]);
+export const easyPayProviderSchema = z.enum(["NAVERPAY", "KAKAOPAY", "TOSSPAY", "PAYCO", "PAYPAL"]);
 export type EasyPayProvider = z.infer<typeof easyPayProviderSchema>;
 
 /**
@@ -188,6 +198,55 @@ export const naverPayCredentialsInputSchema = z.object({
 });
 export type NaverPayCredentialsInput = z.infer<typeof naverPayCredentialsInputSchema>;
 
+/**
+ * PayPal이 받는 통화 중 sayren이 여는 것(이슈 #131 설계 §3b) — PayPal 통화 코드(https://developer.paypal.com/api/rest/reference/currency-codes/) ∩ 통화표
+ * − 원화(PayPal이 받지 않는다) − CNY·MYR(현지 계정 전용) − TWD(부분 환불 소수 문제, 설계 Q4)
+ */
+export const PAYPAL_CURRENCIES = [
+  "USD",
+  "EUR",
+  "JPY",
+  "GBP",
+  "HKD",
+  "SGD",
+  "AUD",
+  "CAD",
+  "THB",
+  "PHP",
+  "NZD",
+  "CHF",
+] as const;
+
+export const payPalCredentialsInputSchema = z.object({
+  clientId: z
+    .string()
+    .trim()
+    .min(10)
+    .max(200)
+    .describe("PayPal REST 앱의 Client ID(테스트 세트는 샌드박스 앱). 공개 값"),
+  currencies: z
+    .array(z.enum(PAYPAL_CURRENCIES))
+    .min(1)
+    .max(PAYPAL_CURRENCIES.length)
+    .describe(
+      "받는 통화 — PayPal 계정에 열어 둔 통화를 고른다. 결제 세션 통화가 여기 있는 주문서에만 PayPal 옵션이 나온다(원화는 받지 않는다)",
+    ),
+  webhookId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .nullable()
+    .optional()
+    .describe(
+      "PayPal 앱에 등록한 웹훅의 ID(선택). 주면 서버 통지의 서명을 검증해 결제 확인을 앞당긴다. 생략·null이면 통지를 받지 않고 주기 확인만 한다",
+    ),
+  clientSecret: secretInput()
+    .optional()
+    .describe("Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+});
+export type PayPalCredentialsInput = z.infer<typeof payPalCredentialsInputSchema>;
+
 const upsertEnvironment = () =>
   pgEnvironmentSchema.describe(
     "저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. " +
@@ -220,6 +279,12 @@ export const upsertNaverPayProviderRequestSchema = z.object({
 });
 export type UpsertNaverPayProviderRequest = z.infer<typeof upsertNaverPayProviderRequestSchema>;
 
+export const upsertPayPalProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: payPalCredentialsInputSchema,
+});
+export type UpsertPayPalProviderRequest = z.infer<typeof upsertPayPalProviderRequestSchema>;
+
 export const updatePaymentProviderRequestSchema = z
   .object({
     enabled: z
@@ -304,6 +369,11 @@ const publicConfigSchema = z.union([
   z.object({ storeId: z.string(), channels: z.array(portOneChannelSchema) }),
   z.object({ cid: z.string() }),
   z.object({ clientId: z.string(), chainId: z.string() }),
+  z.object({
+    clientId: z.string(),
+    currencies: z.array(z.string()),
+    webhookId: z.string().nullable(),
+  }),
 ]);
 
 const verificationSchema = z.object({
@@ -315,7 +385,7 @@ const verificationSchema = z.object({
 export const paymentCredentialSetSchema = z.object({
   environment: pgEnvironmentSchema,
   publicConfig: publicConfigSchema.describe(
-    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`",
+    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`, PayPal은 `{clientId, currencies, webhookId}`",
   ),
   secrets: z
     .array(maskedSecretSchema)
@@ -371,7 +441,7 @@ export const liveGateErrorDetailsSchema = z.object({
 export type LiveGateErrorDetails = z.infer<typeof liveGateErrorDetailsSchema>;
 
 export const paymentProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),
@@ -499,7 +569,7 @@ export const paymentSettingsSchema = z.object({
   providers: z
     .array(paymentProviderSchema)
     .describe(
-      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 카카오페이·네이버페이는 연결했을 때만 여기에 온다" +
+      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 그 밖의 PG(카카오페이·네이버페이 등)는 연결했을 때만 여기에 온다" +
         "(이 PG를 모르는 이전 SDK가 응답을 읽을 수 있게). 연결할 수 있는 PG 전체는 `connectableProviders`다",
     ),
   connectableProviders: z
@@ -539,7 +609,7 @@ export const paymentSettingsSchema = z.object({
 export type PaymentSettings = z.infer<typeof paymentSettingsSchema>;
 
 export const paymentProviderVerificationSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
   result: pgVerificationResultSchema,
   message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
@@ -592,7 +662,7 @@ export type SalesTotals = z.infer<typeof salesTotalsSchema>;
 
 export const salesReportRowSchema = salesTotalsSchema.extend({
   date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
-  provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
+  provider: pgProviderResponseSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
   method: pgPaymentMethodSchema
     .nullable()
     .describe(
@@ -602,17 +672,36 @@ export const salesReportRowSchema = salesTotalsSchema.extend({
 });
 export type SalesReportRow = z.infer<typeof salesReportRowSchema>;
 
+/** 통화별 매출(이슈 #130) — 환산하지 않는다. 금액은 그 통화의 최소 단위다 */
+export const salesReportCurrencySchema = z.object({
+  currency: z.string().describe("결제 통화(ISO 4217)"),
+  summary: salesTotalsSchema.describe("이 통화의 기간 전체 합계"),
+  rows: z.array(salesReportRowSchema).describe("이 통화의 집계 행(`groupBy` 기준)"),
+});
+export type SalesReportCurrency = z.infer<typeof salesReportCurrencySchema>;
+
 export const salesReportSchema = z.object({
   from: z.string(),
   to: z.string(),
   timezone: z.literal("Asia/Seoul"),
-  currency: z.literal("KRW"),
+  currency: z
+    .literal("KRW")
+    .describe(
+      "`summary`·`rows`의 통화. 기본 통화(원화) 결제만 집계한다. 외화 결제는 `byCurrency`에 있다",
+    ),
   groupBy: salesReportGroupBySchema,
-  provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+  provider: pgProviderResponseSchema.nullable().describe("적용된 PG 필터"),
   method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
   includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
   summary: salesTotalsSchema.describe("기간 전체 합계"),
   rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다"),
+  byCurrency: z
+    .array(salesReportCurrencySchema)
+    .optional()
+    .default([])
+    .describe(
+      "통화별 매출(이슈 #130) — 활동이 있는 통화마다 한 항목이고 기본 통화(KRW)도 포함한다. 통화 사이는 환산하지 않는다. 옛 서버 응답은 빈 목록",
+    ),
 });
 export type SalesReport = z.infer<typeof salesReportSchema>;
 
@@ -677,7 +766,9 @@ export const cashReceiptSchema = z.object({
     .int()
     .describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
   issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
-  provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
   issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
   receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
   issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
@@ -708,7 +799,9 @@ export const paymentRecordSchema = z.object({
     .describe(
       "환불 대기 금액 합계(#115) — 주문만 취소하고 아직 환불하지 않은 몫. 결제 상세에서 환불 처리한다",
     ),
-  provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+  provider: pgProviderResponseSchema
+    .nullable()
+    .describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
   method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
   easyPayProvider: easyPayProviderResponseSchema
     .nullable()
@@ -764,7 +857,7 @@ export const paymentAttemptRecordSchema = z.object({
       "PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다",
     ),
   sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   status: paymentAttemptStatusSchema,
   method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
   easyPayProvider: easyPayProviderResponseSchema
@@ -876,7 +969,7 @@ export type SetPlatformTestKeysRequest = z.infer<typeof setPlatformTestKeysReque
 
 /** 결제 상태 PG 한 줄 — 비밀 값·공개 키 없이 연결·사용·환경·테스트모드 키만 */
 export const paymentStatusProviderSchema = z.object({
-  provider: pgProviderSchema,
+  provider: pgProviderResponseSchema,
   displayName: z.string(),
   connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
   enabled: z.boolean().describe("결제에 사용 중인가"),