@sayren/store-sdk 0.11.0 → 0.12.0

package/dist/index.d.mts

@@ -8,9 +8,13 @@ export declare class ApiError extends Error {
   readonly body?: unknown | undefined;
   /** 엔벨로프 `$.error.details` — 에러 코드별 보조 데이터. 없으면 undefined */
   readonly details?: Record<string, unknown> | undefined;
+  /** 엔벨로프 `$.error.docs` — 이 에러 코드를 설명하는 문서 URL. 매핑이 없으면 undefined */
+  readonly docs?: string | undefined;
   constructor(status: number, code: string, message: string, traceId?: string | undefined, body?: unknown | undefined,
   /** 엔벨로프 `$.error.details` — 에러 코드별 보조 데이터. 없으면 undefined */
-  details?: Record<string, unknown> | undefined);
+  details?: Record<string, unknown> | undefined,
+  /** 엔벨로프 `$.error.docs` — 이 에러 코드를 설명하는 문서 URL. 매핑이 없으면 undefined */
+  docs?: string | undefined);
 }
 type TokenSource = string | null | undefined | (() => string | null | undefined);
 type Query = Record<string, string | number | boolean | undefined>;
@@ -619,6 +623,7 @@ export declare const apiLogListQuerySchema: z.ZodObject<{
     "5xx": "5xx";
   }>>;
   q: z.ZodOptional<z.ZodString>;
+  traceId: z.ZodOptional<z.ZodString>;
   cursor: z.ZodOptional<z.ZodString>;
   limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
@@ -1956,6 +1961,34 @@ export declare const webhookDeliveryErrorCodeSchema: z.ZodEnum<{
   WEBHOOK_SUSPENDED: "WEBHOOK_SUSPENDED";
 }>;
 export type WebhookDeliveryErrorCode = z.infer<typeof webhookDeliveryErrorCodeSchema>;
+/**
+ * 실패 원인 분류의 **현재** 값. 응답 스키마(`webhookFailureReasonSchema`)는 문자열로 열려 있다 —
+ * 서버가 값을 더해도 이전 SDK가 목록 파싱에 실패하지 않게 한다(택배 추적 `stage`와 같은 이유).
+ * 모르는 값은 `errorCode`로 판단한다.
+ */
+export declare const WEBHOOK_FAILURE_REASONS: readonly ["DNS", "TLS", "TIMEOUT", "CONNECTION", "HTTP_4XX", "HTTP_5XX", "HTTP_OTHER", "SSRF_BLOCKED", "SUSPENDED"];
+/** 알려진 실패 원인. 응답에는 이 밖의 문자열이 올 수 있다 */
+export type WebhookFailureReason = (typeof WEBHOOK_FAILURE_REASONS)[number];
+export declare const webhookFailureReasonSchema: z.ZodString;
+/**
+ * 대상 리소스 종류의 **현재** 값. 응답 스키마는 문자열로 열려 있다(새 이벤트가 새 리소스를 가리킬 수 있다).
+ */
+export declare const WEBHOOK_RESOURCE_TYPES: readonly ["ORDER", "CLAIM", "PRODUCT", "REVIEW", "INQUIRY"];
+/** 알려진 리소스 종류. 응답에는 이 밖의 문자열이 올 수 있다 */
+export type WebhookResourceType = (typeof WEBHOOK_RESOURCE_TYPES)[number];
+export declare const webhookResourceTypeSchema: z.ZodString;
+/** 이벤트가 가리키는 대상 리소스 — 전송 기록을 주문·상품과 잇는 키 */
+export declare const webhookDeliveryResourceSchema: z.ZodObject<{
+  type: z.ZodString;
+  id: z.ZodString;
+}, z.core.$strip>;
+export type WebhookDeliveryResource = z.infer<typeof webhookDeliveryResourceSchema>;
+/** 발송 요청 헤더 한 줄 (값 마스킹) */
+export declare const webhookRequestHeaderSchema: z.ZodObject<{
+  name: z.ZodString;
+  value: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type WebhookRequestHeader = z.infer<typeof webhookRequestHeaderSchema>;
 /** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
 export declare const webhookDeliverySchema: z.ZodObject<{
   deliveryId: z.ZodString;
@@ -1992,6 +2025,11 @@ export declare const webhookDeliverySchema: z.ZodObject<{
     NON_2XX: "NON_2XX";
     WEBHOOK_SUSPENDED: "WEBHOOK_SUSPENDED";
   }>>;
+  failureReason: z.ZodNullable<z.ZodString>;
+  resource: z.ZodNullable<z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+  }, z.core.$strip>>;
   attemptCount: z.ZodNumber;
   createdAt: z.ZodString;
   attemptedAt: z.ZodNullable<z.ZodString>;
@@ -2000,6 +2038,64 @@ export declare const webhookDeliverySchema: z.ZodObject<{
   redeliveredAs: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;
+/** 발송 본문 최대 노출 길이(바이트). 넘으면 잘라 주고 `payloadTruncated`가 true다 */
+export declare const WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES: number;
+/** 웹훅 전송 기록 상세 — `GET /webhooks/{id}/deliveries/{deliveryId}`. 목록 항목 + 요청 본문·헤더 */
+export declare const webhookDeliveryDetailSchema: z.ZodObject<{
+  deliveryId: z.ZodString;
+  eventId: z.ZodString;
+  eventType: z.ZodEnum<{
+    "ORDER.PAID": "ORDER.PAID";
+    "ORDER.CONFIRMED": "ORDER.CONFIRMED";
+    "ORDER.DISPATCHED": "ORDER.DISPATCHED";
+    "ORDER.DELIVERED": "ORDER.DELIVERED";
+    "ORDER.PURCHASE_DECIDED": "ORDER.PURCHASE_DECIDED";
+    "ORDER.ADDRESS_CHANGE_REQUESTED": "ORDER.ADDRESS_CHANGE_REQUESTED";
+    "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
+    "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
+    "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+    "CLAIM.COMPLETED": "CLAIM.COMPLETED";
+    "INQUIRY.CREATED": "INQUIRY.CREATED";
+    "REVIEW.CREATED": "REVIEW.CREATED";
+    "PRODUCT.OUT_OF_STOCK": "PRODUCT.OUT_OF_STOCK";
+  }>;
+  url: z.ZodString;
+  status: z.ZodEnum<{
+    PENDING: "PENDING";
+    PENDING_RETRY: "PENDING_RETRY";
+    SUCCESS: "SUCCESS";
+    FAILED: "FAILED";
+  }>;
+  responseStatusCode: z.ZodNullable<z.ZodNumber>;
+  responseTimeMs: z.ZodNullable<z.ZodNumber>;
+  responseBodyExcerpt: z.ZodNullable<z.ZodString>;
+  errorCode: z.ZodNullable<z.ZodEnum<{
+    TIMEOUT: "TIMEOUT";
+    CONNECTION_FAILED: "CONNECTION_FAILED";
+    BLOCKED_ADDRESS: "BLOCKED_ADDRESS";
+    NON_2XX: "NON_2XX";
+    WEBHOOK_SUSPENDED: "WEBHOOK_SUSPENDED";
+  }>>;
+  failureReason: z.ZodNullable<z.ZodString>;
+  resource: z.ZodNullable<z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+  }, z.core.$strip>>;
+  attemptCount: z.ZodNumber;
+  createdAt: z.ZodString;
+  attemptedAt: z.ZodNullable<z.ZodString>;
+  nextAttemptAt: z.ZodNullable<z.ZodString>;
+  redeliveryOf: z.ZodNullable<z.ZodString>;
+  redeliveredAs: z.ZodNullable<z.ZodString>;
+  payload: z.ZodString;
+  payloadTruncated: z.ZodBoolean;
+  payloadMasked: z.ZodBoolean;
+  requestHeaders: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WebhookDeliveryDetail = z.infer<typeof webhookDeliveryDetailSchema>;
 /** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
 export declare const webhookDeliveryListQuerySchema: z.ZodObject<{
   status: z.ZodOptional<z.ZodEnum<{
@@ -2008,6 +2104,22 @@ export declare const webhookDeliveryListQuerySchema: z.ZodObject<{
     SUCCESS: "SUCCESS";
     FAILED: "FAILED";
   }>>;
+  eventType: z.ZodOptional<z.ZodEnum<{
+    "ORDER.PAID": "ORDER.PAID";
+    "ORDER.CONFIRMED": "ORDER.CONFIRMED";
+    "ORDER.DISPATCHED": "ORDER.DISPATCHED";
+    "ORDER.DELIVERED": "ORDER.DELIVERED";
+    "ORDER.PURCHASE_DECIDED": "ORDER.PURCHASE_DECIDED";
+    "ORDER.ADDRESS_CHANGE_REQUESTED": "ORDER.ADDRESS_CHANGE_REQUESTED";
+    "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
+    "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
+    "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+    "CLAIM.COMPLETED": "CLAIM.COMPLETED";
+    "INQUIRY.CREATED": "INQUIRY.CREATED";
+    "REVIEW.CREATED": "REVIEW.CREATED";
+    "PRODUCT.OUT_OF_STOCK": "PRODUCT.OUT_OF_STOCK";
+  }>>;
+  resourceId: z.ZodOptional<z.ZodString>;
   limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 export type WebhookDeliveryListParams = z.infer<typeof webhookDeliveryListQuerySchema>;
@@ -2045,6 +2157,13 @@ export declare const webhookTestResultSchema: z.ZodObject<{
     NON_2XX: "NON_2XX";
     WEBHOOK_SUSPENDED: "WEBHOOK_SUSPENDED";
   }>>;
+  failureReason: z.ZodNullable<z.ZodString>;
+  responseBodyExcerpt: z.ZodNullable<z.ZodString>;
+  requestHeaders: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  payload: z.ZodString;
 }, z.core.$strip>;
 export type WebhookTestResult = z.infer<typeof webhookTestResultSchema>;
 export declare const webhookRequestSchema: z.ZodObject<{
@@ -6924,6 +7043,11 @@ export declare function createStoreClient(options: StoreClientOptions): {
       responseTimeMs: number | null;
       responseBodyExcerpt: string | null;
       errorCode: "TIMEOUT" | "CONNECTION_FAILED" | "BLOCKED_ADDRESS" | "NON_2XX" | "WEBHOOK_SUSPENDED" | null;
+      failureReason: string | null;
+      resource: {
+        type: string;
+        id: string;
+      } | null;
       attemptCount: number;
       createdAt: string;
       attemptedAt: string | null;
@@ -6931,6 +7055,40 @@ export declare function createStoreClient(options: StoreClientOptions): {
       redeliveryOf: string | null;
       redeliveredAs: string | null;
     }[]>;
+    /**
+     * 전송 기록 한 건의 상세. 목록 항목에 보낸 요청 본문(최대 16KB)과 요청 헤더가 더해진다.
+     * 실패 원인 분류(`failureReason`)·응답 본문(`responseBodyExcerpt`)으로 원인을 찾고,
+     * `resource.id`를 API 로그 조회의 `q`로 넘겨 같은 리소스의 API 요청과 맞춰 본다.
+     */
+    getDelivery: (webhookId: string, deliveryId: string) => Promise<{
+      deliveryId: string;
+      eventId: string;
+      eventType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED" | "CLAIM.COMPLETED" | "INQUIRY.CREATED" | "REVIEW.CREATED" | "PRODUCT.OUT_OF_STOCK";
+      url: string;
+      status: "PENDING" | "PENDING_RETRY" | "SUCCESS" | "FAILED";
+      responseStatusCode: number | null;
+      responseTimeMs: number | null;
+      responseBodyExcerpt: string | null;
+      errorCode: "TIMEOUT" | "CONNECTION_FAILED" | "BLOCKED_ADDRESS" | "NON_2XX" | "WEBHOOK_SUSPENDED" | null;
+      failureReason: string | null;
+      resource: {
+        type: string;
+        id: string;
+      } | null;
+      attemptCount: number;
+      createdAt: string;
+      attemptedAt: string | null;
+      nextAttemptAt: string | null;
+      redeliveryOf: string | null;
+      redeliveredAs: string | null;
+      payload: string;
+      payloadTruncated: boolean;
+      payloadMasked: boolean;
+      requestHeaders: {
+        name: string;
+        value: string | null;
+      }[];
+    }>;
     /**
      * FAILED 전송 기록 한 건을 같은 eventId로 다시 보낸다(202). 새로 적재된 기록을 돌려주며
      * `redeliveryOf`가 원본 deliveryId다. 원본이 FAILED가 아니면 409 `DELIVERY_NOT_FAILED`,
@@ -6947,6 +7105,11 @@ export declare function createStoreClient(options: StoreClientOptions): {
       responseTimeMs: number | null;
       responseBodyExcerpt: string | null;
       errorCode: "TIMEOUT" | "CONNECTION_FAILED" | "BLOCKED_ADDRESS" | "NON_2XX" | "WEBHOOK_SUSPENDED" | null;
+      failureReason: string | null;
+      resource: {
+        type: string;
+        id: string;
+      } | null;
       attemptCount: number;
       createdAt: string;
       attemptedAt: string | null;
@@ -6969,6 +7132,13 @@ export declare function createStoreClient(options: StoreClientOptions): {
       responseStatusCode: number | null;
       responseTimeMs: number | null;
       errorCode: "TIMEOUT" | "CONNECTION_FAILED" | "BLOCKED_ADDRESS" | "NON_2XX" | "WEBHOOK_SUSPENDED" | null;
+      failureReason: string | null;
+      responseBodyExcerpt: string | null;
+      requestHeaders: {
+        name: string;
+        value: string | null;
+      }[];
+      payload: string;
     }>;
   };
   /** API 로그 (보관 7일, 콘솔 OWNER/ADMIN) */

package/dist/index.mjs

@@ -34,6 +34,11 @@ const errorDetailSchema = z.object({
 	message: z.string(),
 	traceId: z.string().optional(),
 	/**
+	* 이 에러 코드를 설명하는 문서 URL(선택). 서버가 코드별 매핑을 가진 코드에만 실린다 —
+	* 없으면 필드가 아예 없으므로 소비측은 있을 때만 쓴다
+	*/
+	docs: z.url().optional().catch(void 0),
+	/**
 	* 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
 	* `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
 	*/
@@ -69,13 +74,15 @@ var ApiError = class extends Error {
 	traceId;
 	body;
 	details;
-	constructor(status, code, message, traceId, body, details) {
+	docs;
+	constructor(status, code, message, traceId, body, details, docs) {
 		super(message);
 		this.status = status;
 		this.code = code;
 		this.traceId = traceId;
 		this.body = body;
 		this.details = details;
+		this.docs = docs;
 		this.name = "ApiError";
 	}
 };
@@ -88,7 +95,7 @@ var ApiError = class extends Error {
 function toApiError(status, raw) {
 	const envelope = envelopeSchema.safeParse(raw);
 	const detail = envelope.success ? envelope.data.error : errorDetailSchema.safeParse(raw).data ?? null;
-	if (detail) return new ApiError(status, detail.code, detail.message, detail.traceId, raw, detail.details);
+	if (detail) 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) return new ApiError(status, oauth.error, oauth.error_description ?? oauth.error, void 0, raw);
 	return new ApiError(status, "UNKNOWN", `HTTP ${status}`, void 0, raw);
@@ -467,7 +474,8 @@ const apiLogListQuerySchema = z.object({
 	principalType: z.union([z.string(), z.array(z.string())]).transform((value) => (Array.isArray(value) ? value : [value]).flatMap((part) => part.split(",")).map((part) => part.trim()).filter((part) => part.length > 0)).pipe(z.array(apiLogPrincipalTypeSchema).min(1)).optional().describe("호출 주체 유형 필터. 여러 개는 쉼표로 구분한다 (예: `PAT,CLIENT`). 파싱 결과는 배열로 정규화된다"),
 	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)")
 });
@@ -1180,6 +1188,44 @@ const webhookDeliveryErrorCodeSchema = z.enum([
 	"NON_2XX",
 	"WEBHOOK_SUSPENDED"
 ]).describe("전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨");
+/**
+* 실패 원인 분류의 **현재** 값. 응답 스키마(`webhookFailureReasonSchema`)는 문자열로 열려 있다 —
+* 서버가 값을 더해도 이전 SDK가 목록 파싱에 실패하지 않게 한다(택배 추적 `stage`와 같은 이유).
+* 모르는 값은 `errorCode`로 판단한다.
+*/
+const WEBHOOK_FAILURE_REASONS = [
+	"DNS",
+	"TLS",
+	"TIMEOUT",
+	"CONNECTION",
+	"HTTP_4XX",
+	"HTTP_5XX",
+	"HTTP_OTHER",
+	"SSRF_BLOCKED",
+	"SUSPENDED"
+];
+const webhookFailureReasonSchema = z.string().describe("실패 원인 분류(진단용). 현재 값은 `DNS`=호스트 이름을 주소로 바꾸지 못함, `TLS`=인증서·핸드셰이크 실패, `TIMEOUT`=10초 안에 응답 없음, `CONNECTION`=연결 거부·끊김, `HTTP_4XX`·`HTTP_5XX`=그 대역의 응답, `HTTP_OTHER`=2xx·4xx·5xx가 아닌 응답(리다이렉트 등), `SSRF_BLOCKED`=사설·루프백 등 전송이 허용되지 않는 주소, `SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨. `errorCode`보다 잘게 나눈 값이며 둘은 함께 쓸 수 있다. 값이 추가될 수 있으므로 모르는 값은 `errorCode`로 판단한다");
+/**
+* 대상 리소스 종류의 **현재** 값. 응답 스키마는 문자열로 열려 있다(새 이벤트가 새 리소스를 가리킬 수 있다).
+*/
+const WEBHOOK_RESOURCE_TYPES = [
+	"ORDER",
+	"CLAIM",
+	"PRODUCT",
+	"REVIEW",
+	"INQUIRY"
+];
+const webhookResourceTypeSchema = z.string().describe("이벤트가 가리키는 리소스 종류. 현재 값은 `ORDER`·`CLAIM`·`PRODUCT`·`REVIEW`·`INQUIRY`이고 값이 추가될 수 있다");
+/** 이벤트가 가리키는 대상 리소스 — 전송 기록을 주문·상품과 잇는 키 */
+const webhookDeliveryResourceSchema = z.object({
+	type: webhookResourceTypeSchema,
+	id: z.string().describe("리소스 ID. 전송 기록 조회의 `resourceId`, API 로그 조회의 `q`로 그대로 넣을 수 있다")
+});
+/** 발송 요청 헤더 한 줄 (값 마스킹) */
+const webhookRequestHeaderSchema = z.object({
+	name: z.string().describe("헤더 이름"),
+	value: z.string().nullable().describe("헤더 값. 서명(`Sayren-Signature`)처럼 비밀이 섞이는 헤더는 이름만 주고 값은 null이다")
+});
 /** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
 const webhookDeliverySchema = z.object({
 	deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
@@ -1189,8 +1235,10 @@ const webhookDeliverySchema = z.object({
 	status: webhookDeliveryStatusSchema,
 	responseStatusCode: z.number().int().nullable().describe("마지막 시도의 HTTP 응답 코드. 미시도·연결 실패·타임아웃·차단이면 null"),
 	responseTimeMs: z.number().int().nullable().describe("마지막 시도의 응답 시간(ms). 미시도·연결 실패면 null"),
-	responseBodyExcerpt: z.string().nullable().describe("마지막 시도의 응답 본문 앞부분(최대 1,024자). 응답이 없으면 null"),
+	responseBodyExcerpt: z.string().nullable().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().min(0).describe("지금까지의 시도 횟수. 최초 시도 1회 + 재시도 최대 4회"),
 	createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
 	attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
@@ -1198,9 +1246,20 @@ const webhookDeliverySchema = z.object({
 	redeliveryOf: z.string().nullable().describe("수동 재전송으로 생긴 기록이면 원본 전송 기록 ID. 아니면 null"),
 	redeliveredAs: z.string().nullable().describe("이 기록을 원본으로 수동 재전송해 생긴 기록의 전송 기록 ID. 아직 재전송하지 않았으면 null. 재전송은 원본당 1회다")
 });
+/** 발송 본문 최대 노출 길이(바이트). 넘으면 잘라 주고 `payloadTruncated`가 true다 */
+const WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES = 16384;
+/** 웹훅 전송 기록 상세 — `GET /webhooks/{id}/deliveries/{deliveryId}`. 목록 항목 + 요청 본문·헤더 */
+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`는 실제로 보낸 본문(마스킹·자르기 전)의 바이트 수다. 매 시도가 같은 헤더 집합을 쓰고 서명·타임스탬프만 달라진다")
+});
 /** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
 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().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50). 최신 적재순으로 반환하며 보관 기간은 30일이다")
 });
 /** 실패 건 일괄 재전송 응답 — `POST /webhooks/{id}/deliveries/redeliver-failed` */
@@ -1210,7 +1269,11 @@ const webhookTestRequestSchema = z.object({ eventType: eventTypeSchema.describe(
 const webhookTestResultSchema = z.object({
 	responseStatusCode: z.number().int().nullable().describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
 	responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
-	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 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 문자열). 샘플 이벤트다")
 });
 const webhookRequestSchema = z.object({
 	url: z.url().startsWith("https://", "웹훅 URL은 HTTPS만 허용됩니다"),
@@ -3392,6 +3455,12 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			/** 전송 기록 (최신 적재순, 기본 50건·최대 100건, 보관 30일) */
 			listDeliveries: (webhookId, params) => storeHttp.request("GET", path`/webhooks/${webhookId}/deliveries`, z.array(webhookDeliverySchema), { query: params }),
 			/**
+			* 전송 기록 한 건의 상세. 목록 항목에 보낸 요청 본문(최대 16KB)과 요청 헤더가 더해진다.
+			* 실패 원인 분류(`failureReason`)·응답 본문(`responseBodyExcerpt`)으로 원인을 찾고,
+			* `resource.id`를 API 로그 조회의 `q`로 넘겨 같은 리소스의 API 요청과 맞춰 본다.
+			*/
+			getDelivery: (webhookId, deliveryId) => storeHttp.request("GET", path`/webhooks/${webhookId}/deliveries/${deliveryId}`, webhookDeliveryDetailSchema),
+			/**
 			* FAILED 전송 기록 한 건을 같은 eventId로 다시 보낸다(202). 새로 적재된 기록을 돌려주며
 			* `redeliveryOf`가 원본 deliveryId다. 원본이 FAILED가 아니면 409 `DELIVERY_NOT_FAILED`,
 			* 원본이 이미 재전송됐으면 409 `DELIVERY_ALREADY_REDELIVERED`(원본당 1회, 원본의 `redeliveredAs` 참고),
@@ -3831,4 +3900,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { ApiError, CASH_RECEIPT_STATUS_VALUES, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, REFUND_POLICY_DEFAULTS, REMOTE_AREA_ZIP_RANGES, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, UPLOAD_PURPOSE_LIMITS, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, consentActionSchema, consentKindSchema, consentSourceSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedRefundBase, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, resolveRefundPolicy, resolveShippingPolicy, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };
+export { ApiError, CASH_RECEIPT_STATUS_VALUES, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, REFUND_POLICY_DEFAULTS, REMOTE_AREA_ZIP_RANGES, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, UPLOAD_PURPOSE_LIMITS, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_FAILURE_REASONS, WEBHOOK_HEADERS, WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES, WEBHOOK_RESOURCE_TYPES, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, consentActionSchema, consentKindSchema, consentSourceSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedRefundBase, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, resolveRefundPolicy, resolveShippingPolicy, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.11.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,
@@ -984,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/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/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>;