@sayren/store-sdk 0.13.0 → 0.14.0

package/dist/index.mjs

@@ -27,6 +27,162 @@ function base64Utf8(text) {
 	return base64FromBytes(new TextEncoder().encode(text));
 }
 //#endregion
+//#region src/schemas/audit.ts
+/**
+* 감사 로그와 승인 요청 — `/v1/audit-logs`, `/v1/approval-requests` (이슈 #36).
+*
+* 관리 API 쓰기(`/v1/**`의 GET 외 요청)는 모두 요청 단위 기록(`source: REQUEST`) 한 줄을 남긴다. 환불·직권취소 같은
+* 도메인 동작은 그 안에서 변경 전후를 담은 기록(`source: DOMAIN`)을 따로 남기고 `requestId`로 요청 기록과 이어진다.
+*/
+const auditActorTypeSchema = z.enum([
+	"USER",
+	"AGENT",
+	"APP",
+	"TOKEN",
+	"SYSTEM"
+]).describe("행위자 유형. `USER`=콘솔 사용자, `AGENT`=AI 에이전트(MCP·에이전트용 API 토큰), `APP`=앱(OAuth 클라이언트·M2M), `TOKEN`=API 토큰, `SYSTEM`=자동화(주기 잡)");
+const auditActorSchema = z.object({
+	type: auditActorTypeSchema,
+	id: z.string().describe("행위자 ID. `USER`=userId, `TOKEN`·`AGENT`(API 토큰)=`pat:{tokenId}`, `APP`=`client:{clientId}`, `SYSTEM`=`system`. 사람이 앱에 위임한 호출은 `APP`이고 위임한 사람은 `metadata.onBehalfOf`에 있다"),
+	name: z.string().nullable().describe("기록 시점의 표시 이름. 알 수 없으면 null")
+});
+const auditLogSourceSchema = z.enum(["REQUEST", "DOMAIN"]).describe("기록 단위. `REQUEST`=관리 API 쓰기 요청 한 건, `DOMAIN`=환불·취소 같은 도메인 동작의 상세");
+const auditLogOutcomeSchema = z.enum([
+	"SUCCEEDED",
+	"FAILED",
+	"PENDING_APPROVAL",
+	"DENIED",
+	"DRY_RUN"
+]).describe("요청 결과. `PENDING_APPROVAL`=승인 대기로 보류(202), `DENIED`=에이전트 정책으로 거부(403 `AGENT_OPERATION_DENIED`), `DRY_RUN`=드라이런(`x-sayren-dry-run: 1`)이라 실행하지 않음");
+const auditLogSchema = z.object({
+	auditId: z.string().describe("감사 로그 ID"),
+	occurredAt: z.string().describe("기록 일시 (ISO 8601)"),
+	source: auditLogSourceSchema,
+	action: z.string().describe("동작. `REQUEST`는 오퍼레이션 ID(OpenAPI `operationId`, 예: `ProductsController_patch`), `DOMAIN`은 도메인 코드(예: `ORDER_ITEM_CANCELED_BY_SELLER`)"),
+	actor: auditActorSchema,
+	actorRole: z.string().nullable().describe("요청 시점의 스토어 역할. 역할이 없는 토큰·자동화는 null"),
+	target: z.object({
+		type: z.string().describe("대상 리소스 유형 (예: `products`, `order-items`, `claim`)"),
+		id: z.string().nullable().describe("대상 리소스 ID. 목록 대상 요청처럼 하나로 정할 수 없으면 null")
+	}),
+	requestId: z.string().nullable().describe("요청 ID. 같은 요청에서 나온 `REQUEST`·`DOMAIN` 기록이 같은 값을 가진다. 자동화는 null"),
+	method: z.string().nullable().describe("HTTP 메서드 (`REQUEST`만)"),
+	path: z.string().nullable().describe("요청 경로와 쿼리 (`REQUEST`만). 민감한 쿼리 값은 `***`로 가린다"),
+	statusCode: z.number().int().nullable().describe("응답 HTTP 상태 코드 (`REQUEST`만)"),
+	outcome: auditLogOutcomeSchema.nullable().describe("요청 결과 (`REQUEST`만)"),
+	errorCode: z.string().nullable().describe("에러 응답의 `error.code` (실패한 요청만)"),
+	traceId: z.string().nullable().describe("추적 ID. 에러 응답의 `error.traceId`와 같다"),
+	idempotencyKey: z.string().nullable().describe("요청의 멱등키"),
+	approvalId: z.string().nullable().describe("승인 요청 ID. 승인 대기로 보류된 요청과 승인 뒤 실행된 요청에 실린다"),
+	metadata: z.record(z.string(), z.unknown()).describe("부가 정보. 도메인 기록은 변경 전후 값·사유를, 승인 실행 기록은 승인자(`approvedBy`)를 싣는다")
+});
+/** 쉼표 구분 목록 쿼리 → 배열 */
+function commaList(item) {
+	return 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(item).min(1));
+}
+/** 감사 로그 조회 쿼리 — `GET /audit-logs` */
+const auditLogListQuerySchema = z.object({
+	from: z.string().optional().describe("조회 시작 일시 (ISO 8601, 포함)"),
+	to: z.string().optional().describe("조회 종료 일시 (ISO 8601, 미포함)"),
+	actorType: commaList(auditActorTypeSchema).optional().describe("행위자 유형 필터. 여러 개는 쉼표로 구분한다 (예: `AGENT,APP`)"),
+	actorId: z.string().optional().describe("행위자 ID 필터 (정확히 일치)"),
+	action: z.string().optional().describe("동작 필터 (정확히 일치)"),
+	targetType: z.string().optional().describe("대상 유형 필터 (정확히 일치)"),
+	targetId: z.string().optional().describe("대상 ID 필터 (정확히 일치)"),
+	source: auditLogSourceSchema.optional(),
+	outcome: auditLogOutcomeSchema.optional(),
+	requestId: z.string().optional().describe("요청 ID 필터 — 한 요청의 요청·도메인 기록을 함께 본다"),
+	approvalId: z.string().optional().describe("승인 요청 ID 필터"),
+	cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 가장 최신부터"),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50)")
+});
+const auditLogPageSchema = z.object({
+	items: z.array(auditLogSchema),
+	nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null")
+});
+const agentPolicyDecisionSchema = z.enum([
+	"ALLOW",
+	"APPROVAL_REQUIRED",
+	"DENIED"
+]).describe("에이전트 쓰기 판정. `ALLOW`=바로 실행, `APPROVAL_REQUIRED`=콘솔 승인 뒤 실행, `DENIED`=에이전트는 실행할 수 없음");
+const previewValueSchema = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.null()
+]);
+const writePreviewSchema = z.object({
+	operationId: z.string().describe("오퍼레이션 ID"),
+	method: z.string(),
+	path: z.string(),
+	target: z.object({
+		type: z.string(),
+		id: z.string().nullable()
+	}),
+	changes: z.array(z.object({
+		field: z.string().describe("바뀌는 필드"),
+		before: z.unknown().describe("현재 값. 새로 만드는 요청이거나 읽을 수 없으면 null"),
+		after: z.unknown().describe("요청이 넣을 값")
+	})).describe("값이 달라지는 필드. 서버가 현재 값과 비교할 수 있는 오퍼레이션만 채운다"),
+	facts: z.record(z.string(), previewValueSchema).describe("영향 요약 (예: 취소 수량·주문상품 금액·예상 환불액). 오퍼레이션마다 다르다")
+});
+/** `x-sayren-dry-run: 1`을 실은 쓰기 요청의 응답(200) — 실행하지 않고 판정과 영향만 돌려준다 */
+const writeDryRunResultSchema = z.object({
+	dryRun: z.literal(true),
+	decision: agentPolicyDecisionSchema,
+	reason: z.string().nullable().describe("승인 필요·거부 사유. `ALLOW`면 null"),
+	preview: writePreviewSchema
+});
+const approvalStatusSchema = z.enum([
+	"PENDING",
+	"EXECUTING",
+	"SUCCEEDED",
+	"FAILED",
+	"UNKNOWN",
+	"REJECTED",
+	"EXPIRED"
+]).describe("승인 요청 상태. `PENDING` 승인 대기 → 승인하면 `EXECUTING`(원 요청 실행 중) → `SUCCEEDED`·`FAILED`(원 요청의 응답 기준), 거절하면 `REJECTED`, 기한이 지나면 `EXPIRED`. 실행 응답을 받지 못했으면(타임아웃·서버 종료) `UNKNOWN`이다 — 서버가 감사 로그로 결과를 확정하면 `SUCCEEDED`·`FAILED`로 바뀌고, 확정하지 못하면 `UNKNOWN`에 남는다. `UNKNOWN`은 다시 실행하지 않는다(이미 실행됐을 수 있다)");
+const approvalRequestSchema = z.object({
+	approvalId: z.string().describe("승인 요청 ID"),
+	status: approvalStatusSchema,
+	operationId: z.string().describe("보류된 오퍼레이션 ID"),
+	method: z.string().describe("HTTP 메서드"),
+	path: z.string().describe("요청 경로와 쿼리"),
+	body: z.unknown().describe("요청 본문. 승인하면 이 본문 그대로 실행한다. 없으면 null"),
+	idempotencyKey: z.string().nullable().describe("원 요청의 멱등키"),
+	reason: z.string().describe("승인이 필요한 이유"),
+	actor: auditActorSchema.describe("요청한 행위자"),
+	preview: writePreviewSchema.nullable().describe("요청 시점에 서버가 계산한 영향 미리보기"),
+	createdAt: z.string().describe("요청 일시 (ISO 8601)"),
+	expiresAt: z.string().describe("승인 기한 (ISO 8601). 지나면 `EXPIRED`가 된다"),
+	decidedAt: z.string().nullable().describe("승인·거절 일시"),
+	decidedBy: z.object({
+		id: z.string(),
+		name: z.string().nullable()
+	}).nullable().describe("승인·거절한 콘솔 사용자"),
+	decisionNote: z.string().nullable().describe("승인·거절 메모"),
+	executedAt: z.string().nullable().describe("원 요청 실행을 마친 일시"),
+	result: z.object({
+		statusCode: z.number().int().describe("원 요청의 응답 상태 코드"),
+		data: z.unknown().describe("성공 응답의 `data` (큰 응답은 잘린다)"),
+		error: z.object({
+			code: z.string(),
+			message: z.string()
+		}).nullable().describe("실패 응답의 `error` 요약")
+	}).nullable().describe("실행 결과. `SUCCEEDED`·`FAILED`·`UNKNOWN`에서 값이 있다. 감사 로그로 확정한 결과는 `data`가 null이다"),
+	approvalUrl: z.string().nullable().describe("셀러 콘솔의 승인 화면 주소. 이 배포의 콘솔 주소를 알 수 없으면 null")
+});
+const approvalListQuerySchema = z.object({
+	status: commaList(approvalStatusSchema).optional().describe("상태 필터. 여러 개는 쉼표로 구분한다 (예: `PENDING,EXECUTING`)"),
+	cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 가장 최신부터"),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50)")
+});
+const approvalPageSchema = z.object({
+	items: z.array(approvalRequestSchema),
+	nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null")
+});
+const approvalDecisionRequestSchema = z.object({ note: z.string().trim().max(500).optional().describe("승인·거절 메모 (최대 500자)") });
+//#endregion
 //#region src/http.ts
 /** 표준 엔벨로프의 $.error 상세 */
 const errorDetailSchema = z.object({
@@ -86,6 +242,47 @@ var ApiError = class extends Error {
 		this.name = "ApiError";
 	}
 };
+/** 에이전트 쓰기가 승인 대기로 보류됐다(202) */
+const APPROVAL_REQUIRED_CODE = "APPROVAL_REQUIRED";
+/** 같은 멱등키의 승인 요청이 이미 끝났다(200) — 결과는 승인 요청의 `status`·`result`다 */
+const APPROVAL_ALREADY_DECIDED_CODE = "APPROVAL_ALREADY_DECIDED";
+/**
+* 쓰기 요청이 실행되지 않고 승인 흐름에 걸렸다 (이슈 #36). 응답 `data`가 요청한 리소스가 아니라 승인 요청이라
+* 성공 값으로 돌려주지 않는다 — 돌려주면 호출부가 승인 요청을 상품·주문으로 읽는다.
+*
+* - `code = APPROVAL_REQUIRED`(202): 에이전트의 고위험 쓰기가 보류됐다. 아직 아무것도 바뀌지 않았다.
+*   셀러가 콘솔(`approval.approvalUrl`)에서 승인하면 서버가 원 요청을 실행한다. 같은 요청을 다시 보내지 말고
+*   `approvalRequests.get(approvalId)`로 결과를 확인한다.
+* - `code = APPROVAL_ALREADY_DECIDED`(200): 같은 멱등키로 보낸 요청의 승인이 이미 끝났다. `status`가
+*   `SUCCEEDED`·`FAILED`·`UNKNOWN`이면 실행 결과(`approval.result`)를 보고, `REJECTED`·`EXPIRED`면 새 멱등키로 다시 요청한다.
+*/
+var ApprovalPendingError = class extends Error {
+	code;
+	httpStatus;
+	approval;
+	approvalId;
+	/** 승인 요청 상태 */
+	status;
+	constructor(code, httpStatus, approval, message) {
+		super(message);
+		this.code = code;
+		this.httpStatus = httpStatus;
+		this.approval = approval;
+		this.name = "ApprovalPendingError";
+		this.approvalId = approval.approvalId;
+		this.status = approval.status;
+	}
+};
+/** 성공 엔벨로프가 승인 흐름 응답이면 ApprovalPendingError. 그 밖(다른 202 등)은 null */
+function approvalErrorOf(status, json) {
+	const envelope = envelopeSchema.safeParse(json);
+	if (!envelope.success) return null;
+	const { code, message } = envelope.data.meta;
+	if (code !== "APPROVAL_REQUIRED" && code !== "APPROVAL_ALREADY_DECIDED") return null;
+	const approval = approvalRequestSchema.safeParse(envelope.data.data);
+	if (!approval.success) return null;
+	return new ApprovalPendingError(code, status, approval.data, message);
+}
 /**
 * 에러 응답 본문 → ApiError 구성 (에러 형태의 단일 원천).
 * 표준 엔벨로프($.error) 우선, 구형 평면 에러({ code, message }), OAuth 평면 에러
@@ -144,11 +341,18 @@ function createHttp(options) {
 	}
 	return {
 		async request(method, path, schema, request) {
-			const json = await (await send(method, path, request)).json();
+			const response = await send(method, path, request);
+			const json = await response.json();
+			const pending = approvalErrorOf(response.status, json);
+			if (pending) throw pending;
 			return schema.parse(unwrapData(json));
 		},
 		async requestVoid(method, path, request) {
-			await send(method, path, request);
+			const response = await send(method, path, request);
+			if (response.status === 204) return;
+			const json = await response.json().catch(() => null);
+			const pending = approvalErrorOf(response.status, json);
+			if (pending) throw pending;
 		}
 	};
 }
@@ -551,7 +755,8 @@ const apiTokenSchema = z.object({
 	createdByEmail: z.string().nullable().describe("발급자 이메일 (표시용). 계정이 없으면 null"),
 	createdAt: z.string(),
 	expiresAt: z.string().nullable(),
-	lastUsedAt: z.string().nullable()
+	lastUsedAt: z.string().nullable(),
+	agent: z.boolean().default(false).describe("AI 에이전트(MCP)용 토큰인가. true면 이 토큰의 쓰기는 행위자 `AGENT`로 기록되고 에이전트 쓰기 정책(승인 필요·거부)을 따른다")
 });
 /** 생성 응답 — 평문 토큰은 이 응답에서 단 한 번만 노출된다 */
 const apiTokenCreatedSchema = apiTokenSchema.extend({ token: z.string() });
@@ -559,7 +764,9 @@ const apiTokenCreateRequestSchema = z.object({
 	name: z.string().min(1).max(50),
 	scopes: z.array(z.string()).min(1),
 	/** 일 단위 만료. null = 무기한, 생략 = 90일 */
-	expiresInDays: z.number().int().nullable().optional()
+	expiresInDays: z.number().int().nullable().optional(),
+	/** AI 에이전트(MCP)용 토큰. 생략 = false. 발급 뒤에는 바꿀 수 없다 */
+	agent: z.boolean().optional()
 });
 //#endregion
 //#region src/schemas/category.ts
@@ -3488,6 +3695,30 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			/** 최근 24시간 요청 수·에러 수 */
 			summary: () => storeHttp.request("GET", "/api-logs/summary", apiLogSummarySchema)
 		},
+		/** 감사 로그 (관리 API 쓰기의 행위자·대상·결과, 콘솔 OWNER/ADMIN, `audit:r`) */
+		auditLogs: { 
+		/** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+list: (params) => storeHttp.request("GET", "/audit-logs", auditLogPageSchema, { query: params && {
+			...params,
+			actorType: Array.isArray(params.actorType) ? params.actorType.join(",") || void 0 : params.actorType
+		} }) },
+		/**
+		* 승인 요청 — 에이전트의 고위험 쓰기가 202로 보류된 건. 목록·승인·거절은 콘솔 OWNER/ADMIN,
+		* 단건 조회는 요청한 토큰도 할 수 있다(상태 확인용).
+		*/
+		approvalRequests: {
+			list: (params) => storeHttp.request("GET", "/approval-requests", approvalPageSchema, { query: params && {
+				...params,
+				status: Array.isArray(params.status) ? params.status.join(",") || void 0 : params.status
+			} }),
+			get: (approvalId) => storeHttp.request("GET", path`/approval-requests/${approvalId}`, approvalRequestSchema),
+			/**
+			* 승인하면 서버가 원 요청을 그대로 한 번 실행한다. 응답은 실행을 기다리지 않은 `EXECUTING` 상태이고,
+			* 결과(`SUCCEEDED`·`FAILED`·`UNKNOWN`)는 `get`으로 확인한다. 두 번 눌러도 한 번만 실행한다
+			*/
+			approve: (approvalId, body = {}) => storeHttp.request("POST", path`/approval-requests/${approvalId}/approve`, approvalRequestSchema, { body: approvalDecisionRequestSchema.parse(body) }),
+			reject: (approvalId, body = {}) => storeHttp.request("POST", path`/approval-requests/${approvalId}/reject`, approvalRequestSchema, { body: approvalDecisionRequestSchema.parse(body) })
+		},
 		reviews: {
 			list: (params) => storeHttp.request("GET", "/reviews", pageSchema(reviewSchema), { query: params }),
 			get: (reviewId) => storeHttp.request("GET", path`/reviews/${reviewId}`, reviewSchema),
@@ -3602,7 +3833,7 @@ async function exchangeStoreTokenViaOAuth(options) {
 * 서버 인가가 갈라지지 않는다.
 */
 const scopeAccessSchema = z.enum(["r", "rw"]).describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
-/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics·audit는 쓰기 API가 없어 `r`만 존재한다 */
 const STORE_SCOPE_RESOURCES = {
 	product: ["r", "rw"],
 	category: ["r", "rw"],
@@ -3615,7 +3846,8 @@ const STORE_SCOPE_RESOURCES = {
 	webhook: ["r", "rw"],
 	store: ["r", "rw"],
 	member: ["r", "rw"],
-	customer: ["r", "rw"]
+	customer: ["r", "rw"],
+	audit: ["r"]
 };
 const storeScopeResourceSchema = z.enum(Object.keys(STORE_SCOPE_RESOURCES)).describe("스코프 리소스");
 /** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
@@ -3642,7 +3874,8 @@ const STORE_ROLE_SCOPES = {
 		"webhook:rw",
 		"store:rw",
 		"member:rw",
-		"customer:rw"
+		"customer:rw",
+		"audit:r"
 	],
 	ADMIN: [
 		"product:rw",
@@ -3655,7 +3888,8 @@ const STORE_ROLE_SCOPES = {
 		"webhook:rw",
 		"store:rw",
 		"member:rw",
-		"customer:rw"
+		"customer:rw",
+		"audit:r"
 	],
 	STAFF: [
 		"product:rw",
@@ -3938,4 +4172,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, 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 };
+export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, 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, agentPolicyDecisionSchema, 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, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, 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, writeDryRunResultSchema, writePreviewSchema };

package/package.json

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

package/src/client.ts

@@ -38,6 +38,15 @@ import {
   oauthClientRegistrationResponseSchema,
 } from "./schemas/api-client";
 import { type ApiLogListOptions, apiLogPageSchema, apiLogSummarySchema } from "./schemas/api-log";
+import {
+  type ApprovalDecisionRequest,
+  type ApprovalListOptions,
+  type AuditLogListOptions,
+  approvalDecisionRequestSchema,
+  approvalPageSchema,
+  approvalRequestSchema,
+  auditLogPageSchema,
+} from "./schemas/audit";
 import {
   type ApiTokenCreateRequest,
   apiTokenCreatedSchema,
@@ -1044,6 +1053,56 @@ export function createStoreClient(options: StoreClientOptions) {
       summary: () => storeHttp.request("GET", "/api-logs/summary", apiLogSummarySchema),
     },
 
+    /** 감사 로그 (관리 API 쓰기의 행위자·대상·결과, 콘솔 OWNER/ADMIN, `audit:r`) */
+    auditLogs: {
+      /** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+      list: (params?: AuditLogListOptions) =>
+        storeHttp.request("GET", "/audit-logs", auditLogPageSchema, {
+          query: params && {
+            ...params,
+            actorType: Array.isArray(params.actorType)
+              ? params.actorType.join(",") || undefined
+              : params.actorType,
+          },
+        }),
+    },
+
+    /**
+     * 승인 요청 — 에이전트의 고위험 쓰기가 202로 보류된 건. 목록·승인·거절은 콘솔 OWNER/ADMIN,
+     * 단건 조회는 요청한 토큰도 할 수 있다(상태 확인용).
+     */
+    approvalRequests: {
+      list: (params?: ApprovalListOptions) =>
+        storeHttp.request("GET", "/approval-requests", approvalPageSchema, {
+          query: params && {
+            ...params,
+            status: Array.isArray(params.status)
+              ? params.status.join(",") || undefined
+              : params.status,
+          },
+        }),
+      get: (approvalId: string) =>
+        storeHttp.request("GET", path`/approval-requests/${approvalId}`, approvalRequestSchema),
+      /**
+       * 승인하면 서버가 원 요청을 그대로 한 번 실행한다. 응답은 실행을 기다리지 않은 `EXECUTING` 상태이고,
+       * 결과(`SUCCEEDED`·`FAILED`·`UNKNOWN`)는 `get`으로 확인한다. 두 번 눌러도 한 번만 실행한다
+       */
+      approve: (approvalId: string, body: ApprovalDecisionRequest = {}) =>
+        storeHttp.request(
+          "POST",
+          path`/approval-requests/${approvalId}/approve`,
+          approvalRequestSchema,
+          { body: approvalDecisionRequestSchema.parse(body) },
+        ),
+      reject: (approvalId: string, body: ApprovalDecisionRequest = {}) =>
+        storeHttp.request(
+          "POST",
+          path`/approval-requests/${approvalId}/reject`,
+          approvalRequestSchema,
+          { body: approvalDecisionRequestSchema.parse(body) },
+        ),
+    },
+
     reviews: {
       list: (params?: ReviewListParams) =>
         storeHttp.request("GET", "/reviews", pageSchema(reviewSchema), { query: params as Query }),

package/src/http.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type ApprovalRequest, type ApprovalStatus, approvalRequestSchema } from "./schemas/audit";
 
 /** 표준 엔벨로프의 $.error 상세 */
 export const errorDetailSchema = z.object({
@@ -63,6 +64,51 @@ export class ApiError extends Error {
   }
 }
 
+/** 에이전트 쓰기가 승인 대기로 보류됐다(202) */
+export const APPROVAL_REQUIRED_CODE = "APPROVAL_REQUIRED";
+/** 같은 멱등키의 승인 요청이 이미 끝났다(200) — 결과는 승인 요청의 `status`·`result`다 */
+export const APPROVAL_ALREADY_DECIDED_CODE = "APPROVAL_ALREADY_DECIDED";
+
+/**
+ * 쓰기 요청이 실행되지 않고 승인 흐름에 걸렸다 (이슈 #36). 응답 `data`가 요청한 리소스가 아니라 승인 요청이라
+ * 성공 값으로 돌려주지 않는다 — 돌려주면 호출부가 승인 요청을 상품·주문으로 읽는다.
+ *
+ * - `code = APPROVAL_REQUIRED`(202): 에이전트의 고위험 쓰기가 보류됐다. 아직 아무것도 바뀌지 않았다.
+ *   셀러가 콘솔(`approval.approvalUrl`)에서 승인하면 서버가 원 요청을 실행한다. 같은 요청을 다시 보내지 말고
+ *   `approvalRequests.get(approvalId)`로 결과를 확인한다.
+ * - `code = APPROVAL_ALREADY_DECIDED`(200): 같은 멱등키로 보낸 요청의 승인이 이미 끝났다. `status`가
+ *   `SUCCEEDED`·`FAILED`·`UNKNOWN`이면 실행 결과(`approval.result`)를 보고, `REJECTED`·`EXPIRED`면 새 멱등키로 다시 요청한다.
+ */
+export class ApprovalPendingError extends Error {
+  readonly approvalId: string;
+  /** 승인 요청 상태 */
+  readonly status: ApprovalStatus;
+
+  constructor(
+    public readonly code: typeof APPROVAL_REQUIRED_CODE | typeof APPROVAL_ALREADY_DECIDED_CODE,
+    /** HTTP 상태 코드 (202·200) */
+    public readonly httpStatus: number,
+    public readonly approval: ApprovalRequest,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ApprovalPendingError";
+    this.approvalId = approval.approvalId;
+    this.status = approval.status;
+  }
+}
+
+/** 성공 엔벨로프가 승인 흐름 응답이면 ApprovalPendingError. 그 밖(다른 202 등)은 null */
+function approvalErrorOf(status: number, json: unknown): ApprovalPendingError | null {
+  const envelope = envelopeSchema.safeParse(json);
+  if (!envelope.success) return null;
+  const { code, message } = envelope.data.meta;
+  if (code !== APPROVAL_REQUIRED_CODE && code !== APPROVAL_ALREADY_DECIDED_CODE) return null;
+  const approval = approvalRequestSchema.safeParse(envelope.data.data);
+  if (!approval.success) return null;
+  return new ApprovalPendingError(code, status, approval.data, message);
+}
+
 /**
  * 에러 응답 본문 → ApiError 구성 (에러 형태의 단일 원천).
  * 표준 엔벨로프($.error) 우선, 구형 평면 에러({ code, message }), OAuth 평면 에러
@@ -200,10 +246,17 @@ export function createHttp(options: HttpOptions): Http {
     ): Promise<T> {
       const response = await send(method, path, request);
       const json: unknown = await response.json();
+      const pending = approvalErrorOf(response.status, json);
+      if (pending) throw pending;
       return schema.parse(unwrapData(json));
     },
     async requestVoid(method: string, path: string, request?: RequestOptions): Promise<void> {
-      await send(method, path, request);
+      const response = await send(method, path, request);
+      if (response.status === 204) return;
+      // 본문 없는 쓰기도 에이전트면 보류(202)될 수 있다 — 성공으로 삼키지 않는다
+      const json: unknown = await response.json().catch(() => null);
+      const pending = approvalErrorOf(response.status, json);
+      if (pending) throw pending;
     },
   };
 }

package/src/index.ts

@@ -1,7 +1,13 @@
 export type { StoreClient, StoreClientOptions } from "./client";
 export { createStoreClient } from "./client";
 export type { Query, TokenSource } from "./http";
-export { ApiError, buildQuery } from "./http";
+export {
+  APPROVAL_ALREADY_DECIDED_CODE,
+  APPROVAL_REQUIRED_CODE,
+  ApiError,
+  ApprovalPendingError,
+  buildQuery,
+} from "./http";
 export {
   buildAuthorizeUrl,
   createPkcePair,
@@ -14,6 +20,7 @@ export {
 export * from "./schemas/analytics";
 export * from "./schemas/api-client";
 export * from "./schemas/api-log";
+export * from "./schemas/audit";
 export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";