@sayren/store-sdk 0.30.20 → 0.32.0

package/src/schemas/payment.ts

@@ -10,10 +10,21 @@ import { type PageParams, pageSchema } from "./common";
  */
 
 export const pgProviderSchema = z
-  .enum(["tosspayments", "portone"])
-  .describe("PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2)");
+  .enum(["tosspayments", "portone", "kakaopay", "naverpay"])
+  .describe(
+    "PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2), `kakaopay`=카카오페이(직접 연동), `naverpay`=네이버페이 결제형(직접 연동)",
+  );
 export type PgProvider = z.infer<typeof pgProviderSchema>;
 
+/**
+ * 간편결제 전용 PG — 결제수단이 간편결제 하나이고 간편결제사가 PG 자신이다(`kakaopay` → `KAKAOPAY`).
+ * 이 PG는 `easyPayProviders` 설정 없이 결제 옵션이 하나(`EASY_PAY` + 그 간편결제사) 나온다
+ */
+export const DEDICATED_EASY_PAY_PROVIDER = {
+  kakaopay: "KAKAOPAY",
+  naverpay: "NAVERPAY",
+} as const satisfies Partial<Record<PgProvider, string>>;
+
 export const pgPaymentMethodSchema = z
   .enum(["CARD", "BANK_TRANSFER", "VIRTUAL_ACCOUNT", "MOBILE", "EASY_PAY"])
   .describe("결제수단 (스토어프론트 결제 요청의 `paymentMethod`와 같은 값)");
@@ -138,6 +149,45 @@ export const portOneCredentialsInputSchema = z.object({
 });
 export type PortOneCredentialsInput = z.infer<typeof portOneCredentialsInputSchema>;
 
+/** 카카오페이 테스트 가맹점 코드 — 카카오페이 개발자센터의 단건 결제 테스트 CID */
+export const KAKAOPAY_TEST_CID = "TC0ONETIME";
+
+export const kakaoPayCredentialsInputSchema = z.object({
+  cid: z
+    .string()
+    .trim()
+    .min(4)
+    .max(20)
+    .describe(
+      "가맹점 코드(CID). 카카오페이와 계약하면 받는다. 공개 값. 테스트 세트는 `TC0ONETIME`(단건 결제 테스트 CID)을 쓸 수 있다",
+    ),
+  secretKey: secretInput()
+    .optional()
+    .describe(
+      "카카오페이 개발자센터 앱의 Secret key(테스트 세트는 dev, 실결제 세트는 운영 키). 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다",
+    ),
+});
+export type KakaoPayCredentialsInput = z.infer<typeof kakaoPayCredentialsInputSchema>;
+
+export const naverPayCredentialsInputSchema = z.object({
+  clientId: z
+    .string()
+    .trim()
+    .min(4)
+    .max(100)
+    .describe("네이버페이 결제형 가입 후 받은 Client ID. 공개 값 — 결제창에서 쓰인다"),
+  chainId: z
+    .string()
+    .trim()
+    .min(4)
+    .max(100)
+    .describe("네이버페이 Chain ID. 공개 값 — 결제창과 API 요청에 쓰인다"),
+  clientSecret: secretInput()
+    .optional()
+    .describe("Client Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+});
+export type NaverPayCredentialsInput = z.infer<typeof naverPayCredentialsInputSchema>;
+
 const upsertEnvironment = () =>
   pgEnvironmentSchema.describe(
     "저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. " +
@@ -158,6 +208,18 @@ export const upsertPortOneProviderRequestSchema = z.object({
 });
 export type UpsertPortOneProviderRequest = z.infer<typeof upsertPortOneProviderRequestSchema>;
 
+export const upsertKakaoPayProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: kakaoPayCredentialsInputSchema,
+});
+export type UpsertKakaoPayProviderRequest = z.infer<typeof upsertKakaoPayProviderRequestSchema>;
+
+export const upsertNaverPayProviderRequestSchema = z.object({
+  environment: upsertEnvironment(),
+  credentials: naverPayCredentialsInputSchema,
+});
+export type UpsertNaverPayProviderRequest = z.infer<typeof upsertNaverPayProviderRequestSchema>;
+
 export const updatePaymentProviderRequestSchema = z
   .object({
     enabled: z
@@ -240,6 +302,8 @@ export type MaskedSecret = z.infer<typeof maskedSecretSchema>;
 const publicConfigSchema = z.union([
   z.object({ clientKey: z.string() }),
   z.object({ storeId: z.string(), channels: z.array(portOneChannelSchema) }),
+  z.object({ cid: z.string() }),
+  z.object({ clientId: z.string(), chainId: z.string() }),
 ]);
 
 const verificationSchema = z.object({
@@ -251,7 +315,7 @@ const verificationSchema = z.object({
 export const paymentCredentialSetSchema = z.object({
   environment: pgEnvironmentSchema,
   publicConfig: publicConfigSchema.describe(
-    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`",
+    "공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, 네이버페이는 `{clientId, chainId}`",
   ),
   secrets: z
     .array(maskedSecretSchema)
@@ -324,7 +388,8 @@ export const paymentProviderSchema = z.object({
   publicConfig: publicConfigSchema
     .nullable()
     .describe(
-      "활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`. 활성 세트가 없으면 null",
+      "활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`, 카카오페이는 `{cid}`, " +
+        "네이버페이는 `{clientId, chainId}`. 활성 세트가 없으면 null",
     ),
   secrets: z
     .array(maskedSecretSchema)
@@ -345,6 +410,18 @@ export const paymentProviderSchema = z.object({
     })
     .describe("환경별 자격 증명 세트. 등록되지 않은 세트는 null"),
   liveGate: liveGateSchema.describe("라이브 개방 조건. 조건을 모두 충족해야 샌드박스를 끌 수 있다"),
+  platformTestKeys: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "테스트모드 키 활성화. `true`면 TEST 세트가 sayren 지정 테스트 키로 고정된다(TEST 세트를 직접 저장·제거하면 409 `PLATFORM_TEST_KEYS_ENABLED`)",
+    ),
+  platformTestKeysAvailable: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("이 PG에 sayren 지정 테스트 키가 있어 테스트모드 키를 켤 수 있는가"),
   easyPayProviders: z
     .array(easyPayProviderResponseSchema)
     .describe(
@@ -421,7 +498,17 @@ export const paymentSettingsSchema = z.object({
     .describe("결제 도메인 — 결제를 마친 구매자가 돌아올 스토어프론트 origin 목록"),
   providers: z
     .array(paymentProviderSchema)
-    .describe("지원하는 모든 PG. 연결된 것은 우선순위순, 연결되지 않은 것은 뒤에 온다"),
+    .describe(
+      "연결된 PG(우선순위순)와 연결되지 않은 토스페이먼츠·포트원. 카카오페이·네이버페이는 연결했을 때만 여기에 온다" +
+        "(이 PG를 모르는 이전 SDK가 응답을 읽을 수 있게). 연결할 수 있는 PG 전체는 `connectableProviders`다",
+    ),
+  connectableProviders: z
+    .array(paymentProviderSchema)
+    .optional()
+    .default(() => [])
+    .describe(
+      "연결되지 않은 PG 전체(카카오페이·네이버페이 포함). 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다",
+    ),
   environment: pgEnvironmentSchema
     .nullable()
     .optional()
@@ -776,3 +863,38 @@ export interface PaymentListParams extends PageParams {
   /** 환불 대기가 있는 결제만(#115) */
   refundHeld?: boolean;
 }
+
+/** 테스트모드 키 활성화 요청(2026-10-14) — `PUT /v1/store/payment-providers/{provider}/platform-test-keys` */
+export const setPlatformTestKeysRequestSchema = z.object({
+  enabled: z
+    .boolean()
+    .describe(
+      "`true`면 sayren 지정 테스트 키를 TEST 세트로 저장하고 PG를 켠다. `false`면 고정만 푼다(TEST 세트는 그대로)",
+    ),
+});
+export type SetPlatformTestKeysRequest = z.infer<typeof setPlatformTestKeysRequestSchema>;
+
+/** 결제 상태 PG 한 줄 — 비밀 값·공개 키 없이 연결·사용·환경·테스트모드 키만 */
+export const paymentStatusProviderSchema = z.object({
+  provider: pgProviderSchema,
+  displayName: z.string(),
+  connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
+  enabled: z.boolean().describe("결제에 사용 중인가"),
+  environment: pgEnvironmentSchema
+    .nullable()
+    .describe("새 결제에 쓰는 환경. 연결되지 않았으면 null"),
+  platformTestKeys: z.boolean().describe("테스트모드 키 활성화 여부"),
+  platformTestKeysAvailable: z.boolean().describe("sayren 지정 테스트 키로 바로 켤 수 있는가"),
+});
+export type PaymentStatusProvider = z.infer<typeof paymentStatusProviderSchema>;
+
+/** 결제 상태(2026-10-14) — `GET /v1/store/payment-status`. 지원 PG 전체와 상점의 연결 상태 */
+export const paymentStatusSchema = z.object({
+  environment: pgEnvironmentSchema
+    .nullable()
+    .describe("새 결제 세션의 환경(사용 중인 PG 기준). 쓸 수 있는 PG가 없으면 null"),
+  providers: z
+    .array(paymentStatusProviderSchema)
+    .describe("sayren이 지원하는 PG 전체(연결 안 된 PG 포함)"),
+});
+export type PaymentStatus = z.infer<typeof paymentStatusSchema>;

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/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/storefront-hosting.ts

@@ -952,6 +952,20 @@ export type StorefrontEditSession = z.infer<typeof storefrontEditSessionSchema>;
 export const storefrontDevLogsSchema = z.object({
   stdout: z.string(),
   stderr: z.string(),
+  browser: z
+    .array(
+      z.object({
+        seq: z.number().int().describe("세션 안에서 오르는 순번"),
+        at: z.string().describe("받은 시각"),
+        level: z.enum(["error", "warn"]),
+        message: z.string(),
+        url: z.string().describe("로그를 남긴 페이지 경로"),
+      }),
+    )
+    .default([])
+    .describe(
+      "편집 미리보기를 연 브라우저의 오류·경고(window 오류, 처리되지 않은 Promise 거부, console.error·warn) 최근 100건. 미리보기를 열어 둔 동안만 모인다",
+    ),
   at: z.string(),
 });
 export type StorefrontDevLogs = z.infer<typeof storefrontDevLogsSchema>;

package/src/schemas/webhook-event.ts

@@ -320,11 +320,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 +424,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 +486,7 @@ export const webhookEventSchema = z
     productOutOfStockWebhookEventSchema,
     flowNotificationWebhookEventSchema,
     flowStateChangedWebhookEventSchema,
+    inventoryChangedWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",