@sayren/store-sdk 0.10.0 → 0.11.0

package/package.json

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

package/src/client.ts

@@ -128,6 +128,7 @@ import {
   purchaseDecisionExtendResultSchema,
 } from "./schemas/order";
 import {
+  cashReceiptSchema,
   type PaymentListParams,
   type PgEnvironment,
   type PgProvider,
@@ -530,6 +531,12 @@ export function createStoreClient(options: StoreClientOptions) {
           query: params as unknown as Query,
         }),
       get: (orderId: string) => storeHttp.request("GET", path`/orders/${orderId}`, orderSchema),
+      /**
+       * `POST /v1/orders/{orderId}/cash-receipt/reissue` — 실패했거나 재시도 대기 중인 현금영수증을 지금 다시 발급·취소한다.
+       * 콘솔 OWNER·ADMIN 전용(PAT·M2M 403 `INSUFFICIENT_ROLE`). 404 `CASH_RECEIPT_NOT_FOUND`, 409 `CASH_RECEIPT_NOT_REISSUABLE`
+       */
+      reissueCashReceipt: (orderId: string) =>
+        storeHttp.request("POST", path`/orders/${orderId}/cash-receipt/reissue`, cashReceiptSchema),
     },
 
     orderItems: {

package/src/index.ts

@@ -26,6 +26,7 @@ export * from "./schemas/payment";
 export * from "./schemas/product";
 export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
+export * from "./schemas/shipping-policy";
 export * from "./schemas/store";
 export * from "./schemas/upload";
 export * from "./schemas/webhook-event";

package/src/schemas/claim.ts

@@ -30,6 +30,24 @@ export const claimReasonSchema = z.enum([
 
 export type ClaimReason = z.infer<typeof claimReasonSchema>;
 
+/**
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 상품이 반품지를 따로 지정했으면 그 주소다.
+ *
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+ */
+export const claimReturnAddressSchema = z.object({
+  name: z.string().describe("주소 이름(셀러가 붙인 별칭). 예: 본사 물류센터"),
+  contactName: z.string().describe("수취인 이름"),
+  phone: z.string().describe("연락처"),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+});
+
+export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
+
 export const claimSchema = z.object({
   claimId: z.string(),
   type: claimTypeSchema,
@@ -73,6 +91,12 @@ export const claimSchema = z.object({
   holdExpiresAt: z.string().nullable(),
   /** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
   holdUsed: z.boolean(),
+  returnAddress: claimReturnAddressSchema
+    .nullable()
+    .describe(
+      "수거 안내에 쓸 반품지(이슈 #30). 상품이 지정한 반품지, 없으면 스토어 기본 반품지다. " +
+        "취소 클레임과 반품지를 등록하지 않은 스토어는 null",
+    ),
 });
 
 export type Claim = z.infer<typeof claimSchema>;

package/src/schemas/order.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
-import { easyPayProviderResponseSchema } from "./payment";
+import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 
 export const orderSummarySchema = z.object({
   orderId: z.string(),
@@ -107,6 +107,13 @@ export const orderSchema = z.object({
     discountAmount: z.number().int(),
     totalAmount: z.number().int(),
     paidAt: z.string().nullable(),
+    cashReceipt: cashReceiptSchema
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
+      ),
   }),
   testPayment: z
     .boolean()
@@ -201,7 +208,14 @@ export const dispatchRequestSchema = z
     deliveryMethod: deliveryMethodSchema,
     carrierCode: z.string().optional(),
     trackingNumber: z.string().optional(),
-    dispatchedAt: z.string().optional(),
+    /**
+     * 발송 시각. ISO 8601이고 시간대(`Z` 또는 `+09:00`)를 포함해야 한다. 생략하면 현재 시각이다.
+     *
+     * 전에는 `z.string()`이라 아무 문자열이나 그대로 저장됐다. 이 값은 배송 정보 jsonb에 들어가
+     * 자동 배송완료·추적 동기화 잡의 대상 선별 조건이 된다 — 잘못된 한 행이 스토어 구분 없이 도는
+     * 잡 전체를 멈출 수 있어 입력에서 좁혔다. 검증을 통과한 값도 저장 전에 UTC ISO로 정규화한다.
+     */
+    dispatchedAt: z.iso.datetime({ offset: true }).optional(),
   })
   .refine(
     (value) =>
@@ -227,11 +241,65 @@ export const deliveryInfoSchema = z.object({
 
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
 
+/**
+ * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+ * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+ */
+export const trackingStageResponseSchema = z.string();
+
 /** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
 export const deliveryStatusSchema = deliveryInfoSchema.extend({
   trackingEvents: z
-    .array(z.object({ status: z.string(), location: z.string(), occurredAt: z.string() }))
-    .optional(),
+    .array(
+      z.object({
+        status: z.string().describe("택배사가 알려 준 처리 내용(예: 집화처리, 배송출발)"),
+        location: z.string().describe("처리 장소. 모르면 빈 문자열"),
+        occurredAt: z.string(),
+        stage: trackingStageResponseSchema
+          .nullable()
+          .optional()
+          .default(null)
+          .describe(
+            "이 이벤트의 추적 단계. 배달 실패처럼 단계로 나눌 수 없는 이벤트는 null. 서버는 항상 싣는다. " +
+              "현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 값이 추가될 수 있어 문자열로 받는다",
+          ),
+      }),
+    )
+    .optional()
+    .describe("배송 추적 이력. 시각 오름차순(오래된 것부터)"),
+  tracking: z
+    .object({
+      result: z
+        .string()
+        .nullable()
+        .describe(
+          "마지막 추적 조회 결과. 조회에 성공한 적이 없으면 null. " +
+            "현재 값은 `FOUND`(조회됨)·`NOT_FOUND`(택배사 전산에 송장 없음)·`UNSUPPORTED_CARRIER`(추적을 지원하지 않는 택배사)이고 " +
+            "값이 추가될 수 있어 문자열로 받는다",
+        ),
+      stage: trackingStageResponseSchema
+        .nullable()
+        .describe(
+          "현재 추적 단계. 조회되지 않았으면 null. 현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 " +
+            "값이 추가될 수 있어 문자열로 받는다",
+        ),
+      checkedAt: z
+        .string()
+        .nullable()
+        .describe("택배사에서 추적 정보를 마지막으로 받아 온 시각(ISO 8601)"),
+      carrierDeliveredAt: z
+        .string()
+        .nullable()
+        .describe(
+          "택배사가 알려 준 배송완료 시각(ISO 8601). 추적으로 배송완료가 반영되면 주문상품의 `deliveredAt`은 반영 시각이라 이 값과 다를 수 있다",
+        ),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "택배 추적 요약. 택배 발송이 아니거나 추적을 쓰지 않으면 null. 추적이 배송완료면 주문상품이 자동으로 배송완료된다. 서버는 항상 싣는다",
+    ),
 });
 
 export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;

package/src/schemas/payment.ts

@@ -514,6 +514,57 @@ export const paymentAttemptStatusSchema = z
       "새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다",
   );
 
+/**
+ * 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
+ * - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
+ * - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
+ * - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
+ * - `CANCELED`: 전액 환불로 취소됐다
+ * - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
+ * - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
+ */
+export const CASH_RECEIPT_STATUS_VALUES = [
+  "REQUESTED",
+  "PENDING",
+  "ISSUED",
+  "CANCELED",
+  "FAILED",
+  "SKIPPED",
+] as const;
+export type KnownCashReceiptStatus = (typeof CASH_RECEIPT_STATUS_VALUES)[number];
+
+export const cashReceiptSchema = z.object({
+  cashReceiptId: z.string(),
+  status: z
+    .string()
+    .describe(
+      "상태. `REQUESTED` 결제 전 · `PENDING` 발급 대기 · `ISSUED` 발급 · `CANCELED` 취소 · `FAILED` 실패 · `SKIPPED` 발급 대상 아님. 값이 추가될 수 있다",
+    ),
+  type: z.string().describe("용도. `INCOME_DEDUCTION` 소득공제 · `EXPENSE_PROOF` 지출증빙"),
+  identityType: z
+    .string()
+    .describe("식별 번호 종류. `PHONE` 휴대폰 · `CARD` 현금영수증카드 · `BUSINESS` 사업자등록번호"),
+  identityNumberMasked: z
+    .string()
+    .describe("가린 식별 번호 (예: 010****5678). 원문은 조회할 수 없다"),
+  amount: z
+    .number()
+    .int()
+    .describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
+  issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
+  provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+  issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
+  receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
+  issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
+  canceledAt: z.string().nullable().describe("최근 취소 시각 (ISO 8601)"),
+  failCode: z.string().nullable().describe("마지막 실패 코드. 성공하면 비운다"),
+  failMessage: z.string().nullable().describe("마지막 실패 사유"),
+  reissuable: z.boolean().describe("콘솔 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
+  requestedAt: z.string().describe("신청 시각 (ISO 8601)"),
+  updatedAt: z.string().describe("마지막 변경 시각 (ISO 8601)"),
+});
+export type CashReceipt = z.infer<typeof cashReceiptSchema>;
+
 export const paymentRecordSchema = z.object({
   paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
   orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
@@ -542,6 +593,14 @@ export const paymentRecordSchema = z.object({
   failMessage: z.string().nullable().describe("실패 사유"),
   paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
   createdAt: z.string().describe("결제 시작 시각 (ISO 8601)"),
+  cashReceiptStatus: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "현금영수증 상태(`cashReceiptSchema.status`와 같은 값). 신청이 없으면 null. 서버는 항상 싣는다",
+    ),
 });
 export type PaymentRecord = z.infer<typeof paymentRecordSchema>;
 
@@ -601,6 +660,11 @@ export const paymentRecordDetailSchema = paymentRecordSchema.extend({
     .describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
   attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
   refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다"),
+  cashReceipt: cashReceiptSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("현금영수증. 구매자가 신청하지 않았으면 null. 서버는 항상 싣는다"),
 });
 export type PaymentRecordDetail = z.infer<typeof paymentRecordDetailSchema>;
 

package/src/schemas/product.ts

@@ -257,6 +257,30 @@ export const variantStockSchema = z.object({
 
 export type VariantStock = z.infer<typeof variantStockSchema>;
 
+/**
+ * 출고지·반품지 지정 문구 — POST·PUT·PATCH가 같은 규칙을 쓰므로 설명도 한 곳이다 (이슈 #30).
+ *
+ * 세 값이 뜻이 다르다. **생략**은 「정하지 않음」이라 서버가 그 시점 스토어 기본 주소를 박아 저장하고,
+ * **null**은 「스토어 기본을 따른다」는 명시적 비우기다. 주소록 항목은 상품이 참조 중이면 지울 수 없어
+ * (`409 ADDRESS_IN_USE`) 참조를 푸는 수단이 필요한데, 생략을 기본값으로 되채우면 기본 주소는 영원히
+ * 풀리지 않는다 — null이 그 경로다. 배송 묶음 판정은 null을 그 시점 스토어 기본 출고지로 정규화하므로
+ * 두 표현이 배송비를 갈라놓지 않는다.
+ */
+const ADDRESS_DESCRIPTIONS = {
+  shipping:
+    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 생략하면 스토어 기본 출고지를 저장하고, " +
+    "`null`이면 비워 둔다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+  return:
+    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 생략하면 스토어 기본 반품지를 저장하고, " +
+    "`null`이면 비워 둔다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다",
+  patchShipping:
+    "출고지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 출고지를 따른다). " +
+    "이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+  patchReturn:
+    "반품지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 반품지를 따른다). " +
+    "이 스토어의 `RETURN` 주소가 아니면 거부한다",
+} as const;
+
 export const productCreateRequestSchema = z
   .object({
     name: z.string().min(1).max(100),
@@ -284,7 +308,15 @@ export const productCreateRequestSchema = z
     deliveryType: deliveryTypeSchema
       .default("PAID")
       .describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
-    deliveryFee: z.number().int().default(0).describe("배송비. 원 단위"),
+    deliveryFee: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "배송비. 원 단위. **생략하면 스토어 기본 배송비**(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 쓴다. " +
+          "`deliveryType`이 FREE면 0으로 저장한다",
+      ),
     conditionalFreeAmount: z
       .number()
       .int()
@@ -306,8 +338,8 @@ export const productCreateRequestSchema = z
         "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
           "`returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다",
       ),
-    shippingAddressId: z.string().optional(),
-    returnAddressId: z.string().optional(),
+    shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.shipping),
+    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return),
   })
   .extend(optionModelRequestSchema.shape);
 
@@ -319,6 +351,13 @@ export const productPatchRequestSchema = z
     salePrice: z.number().int().multipleOf(10).optional(),
     status: productStatusSchema.optional(),
     deliveryFee: z.number().int().optional(),
+    // PATCH의 생략은 「바꾸지 않음」이다 — 기본 주소로 되채우지 않는다. 비우려면 `null`을 준다
+    shippingAddressId: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(ADDRESS_DESCRIPTIONS.patchShipping),
+    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",