@sayren/store-sdk 0.11.0 → 0.13.0

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` 참고),
@@ -3599,6 +3668,44 @@ const STORE_ROLE_SCOPES = {
 	]
 };
 //#endregion
+//#region src/schemas/telemetry.ts
+/**
+* MCP 도구 호출 계측 (`POST /v1/telemetry/mcp`, 이슈 #34).
+*
+* `@sayren/mcp`가 `verify_storefront` 같은 도구를 돌린 뒤 결과 요약을 보낸다. 목적은 하나다 —
+* AI가 만든 스토어프론트가 **처음에** 규칙을 통과하는지, 통과하지 못하면 어떤 규칙에서 막히는지를
+* 세는 것이다. 그 숫자가 규칙과 안내를 고치는 근거가 된다.
+*
+* **보내지 않는 것**: 파일 경로·소스 코드·위반 상세(`detail`)·토큰·사람 식별자. 규칙 id와 개수뿐이다.
+* 테넌트는 요청 토큰이 정한다(본문에 스토어 id가 없다). 옵트아웃은 클라이언트의 `SAYREN_TELEMETRY=0`이다.
+*
+* 알 수 없는 키는 저장하지 않고 버린다(`.strict()`를 쓰지 않는다) — 새 버전 클라이언트가 필드를
+* 하나 더 실었다고 계측 전체가 400으로 날아가면 그 버전의 숫자가 통째로 빈다.
+*/
+/** 규칙 하나의 검사 결과. `ruleId`는 늘어나므로 enum이 아니라 형식만 좁힌다 */
+const mcpRuleResultSchema = z.object({
+	ruleId: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/, "규칙 id는 소문자·숫자·하이픈입니다").describe("검사한 규칙 id (예: `payment-popup-prepare`)"),
+	status: z.enum(["pass", "violation"]).describe("통과했는가"),
+	count: z.number().int().min(0).max(1e4).describe("이 규칙으로 잡힌 위반 수. 통과면 0")
+});
+/**
+* 한 번에 실을 수 있는 규칙 결과 수 — 규칙 수(현재 16개)의 두 배까지다.
+*
+* 규칙 수 수준으로 좁게 둔다. 이 배열이 그대로 `mcp_tool_events.results` jsonb가 되므로 상한이
+* 넉넉하면 한 행의 크기가 그만큼 커지고, 집계가 그 jsonb를 펼친다.
+*/
+const MCP_TELEMETRY_MAX_RESULTS = 32;
+const mcpToolEventSchema = z.object({
+	tool: z.string().regex(/^[a-z][a-z0-9_]{0,39}$/, "도구 이름 형식이 올바르지 않습니다").describe("도구 이름 (예: `verify_storefront`). CLI가 부른 검사는 `create`"),
+	clientVersion: z.string().max(40).regex(/^[\w.+-]+$/, "버전 형식이 올바르지 않습니다").optional().describe("`@sayren/mcp` 버전. 버전별로 첫 통과율이 나아졌는지 본다"),
+	sessionId: z.string().min(8).max(64).regex(/^[A-Za-z0-9_-]+$/, "세션 id 형식이 올바르지 않습니다").describe("클라이언트 프로세스당 랜덤 값. 사람·기기를 식별하지 않는다"),
+	attempt: z.number().int().min(1).max(1e3).describe("이 세션 안에서 같은 도구를 부른 순번(1부터)"),
+	durationMs: z.number().int().min(0).max(36e5).optional().describe("도구 실행 시간(ms)"),
+	ok: z.boolean().describe("위반이 없었는가"),
+	checkedFiles: z.number().int().min(0).max(1e5).describe("검사한 소스 파일 수"),
+	results: z.array(mcpRuleResultSchema).max(32).refine((results) => new Set(results.map((result) => result.ruleId)).size === results.length, { message: "같은 규칙 id를 두 번 실을 수 없습니다" }).describe("규칙별 통과·위반. 규칙 id는 중복될 수 없고 파일 경로와 위반 상세는 싣지 않는다")
+});
+//#endregion
 //#region src/schemas/webhook-event.ts
 const envelopeFields = {
 	id: z.string().describe("이벤트 ID (`evt_…`, 테스트 전송은 `evt_test_…`). 중복 제거 키"),
@@ -3831,4 +3938,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, MCP_TELEMETRY_MAX_RESULTS, 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, mcpRuleResultSchema, mcpToolEventSchema, 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.13.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/index.ts

@@ -28,6 +28,7 @@ export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
 export * from "./schemas/store";
+export * from "./schemas/telemetry";
 export * from "./schemas/upload";
 export * from "./schemas/webhook-event";
 export {

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>;
 

package/src/schemas/telemetry.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+/**
+ * MCP 도구 호출 계측 (`POST /v1/telemetry/mcp`, 이슈 #34).
+ *
+ * `@sayren/mcp`가 `verify_storefront` 같은 도구를 돌린 뒤 결과 요약을 보낸다. 목적은 하나다 —
+ * AI가 만든 스토어프론트가 **처음에** 규칙을 통과하는지, 통과하지 못하면 어떤 규칙에서 막히는지를
+ * 세는 것이다. 그 숫자가 규칙과 안내를 고치는 근거가 된다.
+ *
+ * **보내지 않는 것**: 파일 경로·소스 코드·위반 상세(`detail`)·토큰·사람 식별자. 규칙 id와 개수뿐이다.
+ * 테넌트는 요청 토큰이 정한다(본문에 스토어 id가 없다). 옵트아웃은 클라이언트의 `SAYREN_TELEMETRY=0`이다.
+ *
+ * 알 수 없는 키는 저장하지 않고 버린다(`.strict()`를 쓰지 않는다) — 새 버전 클라이언트가 필드를
+ * 하나 더 실었다고 계측 전체가 400으로 날아가면 그 버전의 숫자가 통째로 빈다.
+ */
+
+/** 규칙 하나의 검사 결과. `ruleId`는 늘어나므로 enum이 아니라 형식만 좁힌다 */
+export const mcpRuleResultSchema = z.object({
+  ruleId: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9-]*$/, "규칙 id는 소문자·숫자·하이픈입니다")
+    .describe("검사한 규칙 id (예: `payment-popup-prepare`)"),
+  status: z.enum(["pass", "violation"]).describe("통과했는가"),
+  count: z.number().int().min(0).max(10_000).describe("이 규칙으로 잡힌 위반 수. 통과면 0"),
+});
+export type McpRuleResult = z.infer<typeof mcpRuleResultSchema>;
+
+/**
+ * 한 번에 실을 수 있는 규칙 결과 수 — 규칙 수(현재 16개)의 두 배까지다.
+ *
+ * 규칙 수 수준으로 좁게 둔다. 이 배열이 그대로 `mcp_tool_events.results` jsonb가 되므로 상한이
+ * 넉넉하면 한 행의 크기가 그만큼 커지고, 집계가 그 jsonb를 펼친다.
+ */
+export const MCP_TELEMETRY_MAX_RESULTS = 32;
+
+export const mcpToolEventSchema = z.object({
+  tool: z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{0,39}$/, "도구 이름 형식이 올바르지 않습니다")
+    .describe("도구 이름 (예: `verify_storefront`). CLI가 부른 검사는 `create`"),
+  clientVersion: z
+    .string()
+    .max(40)
+    .regex(/^[\w.+-]+$/, "버전 형식이 올바르지 않습니다")
+    .optional()
+    .describe("`@sayren/mcp` 버전. 버전별로 첫 통과율이 나아졌는지 본다"),
+  sessionId: z
+    .string()
+    .min(8)
+    .max(64)
+    .regex(/^[A-Za-z0-9_-]+$/, "세션 id 형식이 올바르지 않습니다")
+    .describe("클라이언트 프로세스당 랜덤 값. 사람·기기를 식별하지 않는다"),
+  attempt: z
+    .number()
+    .int()
+    .min(1)
+    .max(1_000)
+    .describe("이 세션 안에서 같은 도구를 부른 순번(1부터)"),
+  durationMs: z.number().int().min(0).max(3_600_000).optional().describe("도구 실행 시간(ms)"),
+  ok: z.boolean().describe("위반이 없었는가"),
+  checkedFiles: z.number().int().min(0).max(100_000).describe("검사한 소스 파일 수"),
+  results: z
+    .array(mcpRuleResultSchema)
+    .max(MCP_TELEMETRY_MAX_RESULTS)
+    // 규칙 하나당 한 줄이다. 같은 id를 여러 줄로 실으면 집계가 한 스토어의 한 규칙을 몇 번 세야
+    // 하는지 정할 수 없고, 상한만큼 같은 규칙을 반복해 보내는 것이 저장을 부풀리는 길이 된다.
+    .refine((results) => new Set(results.map((result) => result.ruleId)).size === results.length, {
+      message: "같은 규칙 id를 두 번 실을 수 없습니다",
+    })
+    .describe("규칙별 통과·위반. 규칙 id는 중복될 수 없고 파일 경로와 위반 상세는 싣지 않는다"),
+});
+export type McpToolEvent = z.infer<typeof mcpToolEventSchema>;