@sayren/store-sdk 0.10.0 → 0.12.0

package/package.json

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

package/src/client.ts

@@ -101,6 +101,7 @@ import {
   type WebhookRequest,
   type WebhookTestRequest,
   webhookCreatedSchema,
+  webhookDeliveryDetailSchema,
   webhookDeliverySchema,
   webhookRedeliverFailedResultSchema,
   webhookRequestSchema,
@@ -128,6 +129,7 @@ import {
   purchaseDecisionExtendResultSchema,
 } from "./schemas/order";
 import {
+  cashReceiptSchema,
   type PaymentListParams,
   type PgEnvironment,
   type PgProvider,
@@ -530,6 +532,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: {
@@ -977,6 +985,17 @@ export function createStoreClient(options: StoreClientOptions) {
           z.array(webhookDeliverySchema),
           { query: params as Query },
         ),
+      /**
+       * 전송 기록 한 건의 상세. 목록 항목에 보낸 요청 본문(최대 16KB)과 요청 헤더가 더해진다.
+       * 실패 원인 분류(`failureReason`)·응답 본문(`responseBodyExcerpt`)으로 원인을 찾고,
+       * `resource.id`를 API 로그 조회의 `q`로 넘겨 같은 리소스의 API 요청과 맞춰 본다.
+       */
+      getDelivery: (webhookId: string, deliveryId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/webhooks/${webhookId}/deliveries/${deliveryId}`,
+          webhookDeliveryDetailSchema,
+        ),
       /**
        * FAILED 전송 기록 한 건을 같은 eventId로 다시 보낸다(202). 새로 적재된 기록을 돌려주며
        * `redeliveryOf`가 원본 deliveryId다. 원본이 FAILED가 아니면 409 `DELIVERY_NOT_FAILED`,

package/src/http.ts

@@ -5,6 +5,11 @@ export const errorDetailSchema = z.object({
   code: z.string(),
   message: z.string(),
   traceId: z.string().optional(),
+  /**
+   * 이 에러 코드를 설명하는 문서 URL(선택). 서버가 코드별 매핑을 가진 코드에만 실린다 —
+   * 없으면 필드가 아예 없으므로 소비측은 있을 때만 쓴다
+   */
+  docs: z.url().optional().catch(undefined),
   /**
    * 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
    * `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
@@ -50,6 +55,8 @@ export class ApiError extends Error {
     public readonly body?: unknown,
     /** 엔벨로프 `$.error.details` — 에러 코드별 보조 데이터. 없으면 undefined */
     public readonly details?: Record<string, unknown>,
+    /** 엔벨로프 `$.error.docs` — 이 에러 코드를 설명하는 문서 URL. 매핑이 없으면 undefined */
+    public readonly docs?: string,
   ) {
     super(message);
     this.name = "ApiError";
@@ -68,7 +75,15 @@ export function toApiError(status: number, raw: unknown): ApiError {
     ? envelope.data.error
     : (errorDetailSchema.safeParse(raw).data ?? null);
   if (detail) {
-    return new ApiError(status, detail.code, detail.message, detail.traceId, raw, detail.details);
+    return new ApiError(
+      status,
+      detail.code,
+      detail.message,
+      detail.traceId,
+      raw,
+      detail.details,
+      detail.docs,
+    );
   }
   const oauth = envelope.success ? null : oauthErrorSchema.safeParse(raw).data;
   if (oauth) {

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/api-log.ts

@@ -68,7 +68,18 @@ export const apiLogListQuerySchema = z.object({
     ),
   principalId: z.string().optional().describe("호출 주체 ID 필터"),
   status: apiLogStatusFilterSchema.optional(),
-  q: z.string().optional().describe("경로 부분 일치 검색어"),
+  q: z
+    .string()
+    .optional()
+    .describe(
+      "경로 부분 일치 검색어. 리소스 id(예: `ord_…`)를 넣으면 그 리소스를 건드린 요청만 남으므로 웹훅 전송 기록의 `resource.id`와 짝지어 쓴다",
+    ),
+  traceId: z
+    .string()
+    .optional()
+    .describe(
+      "추적 ID 필터(정확히 일치). 에러 응답 `error.traceId` 값을 그대로 넣어 그 요청 한 건을 찾는다",
+    ),
   cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 가장 최신부터"),
   limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50)"),
 });

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

@@ -208,6 +208,71 @@ export const webhookDeliveryErrorCodeSchema = z
   );
 export type WebhookDeliveryErrorCode = z.infer<typeof webhookDeliveryErrorCodeSchema>;
 
+/**
+ * 실패 원인 분류의 **현재** 값. 응답 스키마(`webhookFailureReasonSchema`)는 문자열로 열려 있다 —
+ * 서버가 값을 더해도 이전 SDK가 목록 파싱에 실패하지 않게 한다(택배 추적 `stage`와 같은 이유).
+ * 모르는 값은 `errorCode`로 판단한다.
+ */
+export const WEBHOOK_FAILURE_REASONS = [
+  "DNS",
+  "TLS",
+  "TIMEOUT",
+  "CONNECTION",
+  "HTTP_4XX",
+  "HTTP_5XX",
+  "HTTP_OTHER",
+  "SSRF_BLOCKED",
+  "SUSPENDED",
+] as const;
+/** 알려진 실패 원인. 응답에는 이 밖의 문자열이 올 수 있다 */
+export type WebhookFailureReason = (typeof WEBHOOK_FAILURE_REASONS)[number];
+
+export const webhookFailureReasonSchema = z
+  .string()
+  .describe(
+    "실패 원인 분류(진단용). 현재 값은 `DNS`=호스트 이름을 주소로 바꾸지 못함, `TLS`=인증서·핸드셰이크 실패, " +
+      "`TIMEOUT`=10초 안에 응답 없음, `CONNECTION`=연결 거부·끊김, `HTTP_4XX`·`HTTP_5XX`=그 대역의 응답, " +
+      "`HTTP_OTHER`=2xx·4xx·5xx가 아닌 응답(리다이렉트 등), `SSRF_BLOCKED`=사설·루프백 등 전송이 허용되지 않는 주소, " +
+      "`SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨. `errorCode`보다 잘게 나눈 값이며 둘은 함께 쓸 수 있다. " +
+      "값이 추가될 수 있으므로 모르는 값은 `errorCode`로 판단한다",
+  );
+
+/**
+ * 대상 리소스 종류의 **현재** 값. 응답 스키마는 문자열로 열려 있다(새 이벤트가 새 리소스를 가리킬 수 있다).
+ */
+export const WEBHOOK_RESOURCE_TYPES = ["ORDER", "CLAIM", "PRODUCT", "REVIEW", "INQUIRY"] as const;
+/** 알려진 리소스 종류. 응답에는 이 밖의 문자열이 올 수 있다 */
+export type WebhookResourceType = (typeof WEBHOOK_RESOURCE_TYPES)[number];
+
+export const webhookResourceTypeSchema = z
+  .string()
+  .describe(
+    "이벤트가 가리키는 리소스 종류. 현재 값은 `ORDER`·`CLAIM`·`PRODUCT`·`REVIEW`·`INQUIRY`이고 값이 추가될 수 있다",
+  );
+
+/** 이벤트가 가리키는 대상 리소스 — 전송 기록을 주문·상품과 잇는 키 */
+export const webhookDeliveryResourceSchema = z.object({
+  type: webhookResourceTypeSchema,
+  id: z
+    .string()
+    .describe(
+      "리소스 ID. 전송 기록 조회의 `resourceId`, API 로그 조회의 `q`로 그대로 넣을 수 있다",
+    ),
+});
+export type WebhookDeliveryResource = z.infer<typeof webhookDeliveryResourceSchema>;
+
+/** 발송 요청 헤더 한 줄 (값 마스킹) */
+export const webhookRequestHeaderSchema = z.object({
+  name: z.string().describe("헤더 이름"),
+  value: z
+    .string()
+    .nullable()
+    .describe(
+      "헤더 값. 서명(`Sayren-Signature`)처럼 비밀이 섞이는 헤더는 이름만 주고 값은 null이다",
+    ),
+});
+export type WebhookRequestHeader = z.infer<typeof webhookRequestHeaderSchema>;
+
 /** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
 export const webhookDeliverySchema = z.object({
   deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
@@ -232,10 +297,27 @@ export const webhookDeliverySchema = z.object({
   responseBodyExcerpt: z
     .string()
     .nullable()
-    .describe("마지막 시도의 응답 본문 앞부분(최대 1,024자). 응답이 없으면 null"),
+    .describe(
+      "마지막 시도의 응답 본문 앞부분(최대 4,096자). 응답이 없으면 null. 가린 뒤에 자른다. " +
+        "키 이름에 `authorization`·`token`·`secret`·`password`·`key`·`signature`·`credential`·`cookie`가 " +
+        "**들어 있으면**(부분 일치, 대소문자 무시. 예: `apiKey`·`access_token`·`keyword`) 그 값을 `***`로 가린다. " +
+        "값이 객체·배열이면 통째로 가린다. 평문 `Authorization: …` 같은 헤더 줄, `Bearer <토큰>`, " +
+        "쿼리 형식 `access_token=…`, 끝에서 잘려 닫히지 않은 값도 가린다",
+    ),
   errorCode: webhookDeliveryErrorCodeSchema
     .nullable()
     .describe("마지막 시도의 실패 사유. 성공했거나 미시도면 null"),
+  failureReason: webhookFailureReasonSchema
+    .nullable()
+    .describe(
+      "마지막 시도의 실패 원인 분류. 성공했거나 미시도면 null. `errorCode`를 더 잘게 나눈 진단 값이다",
+    ),
+  resource: webhookDeliveryResourceSchema
+    .nullable()
+    .describe(
+      "이벤트가 가리키는 대상 리소스. 리소스를 특정할 수 없는 이벤트면 null. " +
+        "이 값으로 전송 기록(`resourceId`)과 API 로그(`q`)를 오갈 수 있다",
+    ),
   attemptCount: z
     .number()
     .int()
@@ -260,9 +342,47 @@ export const webhookDeliverySchema = z.object({
 });
 export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;
 
+/** 발송 본문 최대 노출 길이(바이트). 넘으면 잘라 주고 `payloadTruncated`가 true다 */
+export const WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES = 16 * 1024;
+
+/** 웹훅 전송 기록 상세 — `GET /webhooks/{id}/deliveries/{deliveryId}`. 목록 항목 + 요청 본문·헤더 */
+export const webhookDeliveryDetailSchema = webhookDeliverySchema.extend({
+  payload: z
+    .string()
+    .describe(
+      "수신 서버로 보낸 요청 본문 그대로(JSON 문자열). 서명은 이 문자열을 대상으로 계산한다. " +
+        `최대 ${WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES / 1024}KB까지 주고 넘으면 잘라 준다`,
+    ),
+  payloadTruncated: z
+    .boolean()
+    .describe("본문이 길어서 잘렸으면 true. true면 `payload`는 유효한 JSON이 아니다"),
+  payloadMasked: z
+    .boolean()
+    .describe(
+      "민감 키 마스킹(`responseBodyExcerpt`와 같은 키 이름 규칙)이 본문을 바꿨으면 true. " +
+        "true면 `payload`는 보낸 본문과 달라 서명을 맞춰 볼 수 없다. 이벤트 본문에는 보통 민감 키가 없어 false다",
+    ),
+  requestHeaders: z
+    .array(webhookRequestHeaderSchema)
+    .describe(
+      "발송 요청에 실은 헤더. 값은 전송 시점 그대로이나 서명 헤더는 이름만 주고 값은 null이다. " +
+        "`Content-Length`는 실제로 보낸 본문(마스킹·자르기 전)의 바이트 수다. " +
+        "매 시도가 같은 헤더 집합을 쓰고 서명·타임스탬프만 달라진다",
+    ),
+});
+export type WebhookDeliveryDetail = z.infer<typeof webhookDeliveryDetailSchema>;
+
 /** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
 export const webhookDeliveryListQuerySchema = z.object({
   status: webhookDeliveryStatusSchema.optional().describe("전송 상태 필터. 생략하면 전체"),
+  eventType: eventTypeSchema.optional().describe("이벤트 타입 필터. 생략하면 전체"),
+  resourceId: z
+    .string()
+    .optional()
+    .describe(
+      "대상 리소스 ID 필터(정확히 일치). 주문·클레임·상품·리뷰·문의 id를 넣으면 그 리소스의 이벤트만 남는다. " +
+        "같은 id로 API 로그를 `q`로 검색하면 그 리소스를 건드린 API 요청을 볼 수 있다",
+    ),
   limit: z.coerce
     .number()
     .int()
@@ -299,6 +419,19 @@ export const webhookTestResultSchema = z.object({
     .describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
   responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
   errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 null"),
+  failureReason: webhookFailureReasonSchema
+    .nullable()
+    .describe("실패 원인 분류. 2xx 응답이면 null"),
+  responseBodyExcerpt: z
+    .string()
+    .nullable()
+    .describe(
+      "응답 본문 앞부분(최대 4,096자). 규칙은 전송 기록의 `responseBodyExcerpt`와 같다. 응답이 없으면 null",
+    ),
+  requestHeaders: z
+    .array(webhookRequestHeaderSchema)
+    .describe("보낸 요청 헤더. 서명 헤더는 이름만 주고 값은 null이다"),
+  payload: z.string().describe("보낸 요청 본문 그대로(JSON 문자열). 샘플 이벤트다"),
 });
 export type WebhookTestResult = z.infer<typeof webhookTestResultSchema>;
 

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개 필드가 필요합니다",