@sayren/store-sdk 0.12.0 → 0.14.0

package/dist/index.d.mts

@@ -1,5 +1,378 @@
 import { a as WEBHOOK_HEADERS, i as WEBHOOK_EVENT_TYPE_HEADER, n as WEBHOOK_DELIVERY_ID_HEADER, o as WEBHOOK_SIGNATURE_HEADER, r as WEBHOOK_EVENT_ID_HEADER, s as WEBHOOK_USER_AGENT, t as WEBHOOK_DEFAULT_TOLERANCE_SEC } from "./webhook-headers-D6QmPdEJ.mjs";
 import { z } from "zod";
+//#region src/schemas/audit.d.ts
+/**
+ * 감사 로그와 승인 요청 — `/v1/audit-logs`, `/v1/approval-requests` (이슈 #36).
+ *
+ * 관리 API 쓰기(`/v1/**`의 GET 외 요청)는 모두 요청 단위 기록(`source: REQUEST`) 한 줄을 남긴다. 환불·직권취소 같은
+ * 도메인 동작은 그 안에서 변경 전후를 담은 기록(`source: DOMAIN`)을 따로 남기고 `requestId`로 요청 기록과 이어진다.
+ */
+export declare const auditActorTypeSchema: z.ZodEnum<{
+  USER: "USER";
+  AGENT: "AGENT";
+  APP: "APP";
+  TOKEN: "TOKEN";
+  SYSTEM: "SYSTEM";
+}>;
+export type AuditActorType = z.infer<typeof auditActorTypeSchema>;
+export declare const auditActorSchema: z.ZodObject<{
+  type: z.ZodEnum<{
+    USER: "USER";
+    AGENT: "AGENT";
+    APP: "APP";
+    TOKEN: "TOKEN";
+    SYSTEM: "SYSTEM";
+  }>;
+  id: z.ZodString;
+  name: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AuditActor = z.infer<typeof auditActorSchema>;
+export declare const auditLogSourceSchema: z.ZodEnum<{
+  REQUEST: "REQUEST";
+  DOMAIN: "DOMAIN";
+}>;
+export type AuditLogSource = z.infer<typeof auditLogSourceSchema>;
+export declare const auditLogOutcomeSchema: z.ZodEnum<{
+  FAILED: "FAILED";
+  SUCCEEDED: "SUCCEEDED";
+  PENDING_APPROVAL: "PENDING_APPROVAL";
+  DENIED: "DENIED";
+  DRY_RUN: "DRY_RUN";
+}>;
+export type AuditLogOutcome = z.infer<typeof auditLogOutcomeSchema>;
+export declare const auditLogSchema: z.ZodObject<{
+  auditId: z.ZodString;
+  occurredAt: z.ZodString;
+  source: z.ZodEnum<{
+    REQUEST: "REQUEST";
+    DOMAIN: "DOMAIN";
+  }>;
+  action: z.ZodString;
+  actor: z.ZodObject<{
+    type: z.ZodEnum<{
+      USER: "USER";
+      AGENT: "AGENT";
+      APP: "APP";
+      TOKEN: "TOKEN";
+      SYSTEM: "SYSTEM";
+    }>;
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  actorRole: z.ZodNullable<z.ZodString>;
+  target: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  requestId: z.ZodNullable<z.ZodString>;
+  method: z.ZodNullable<z.ZodString>;
+  path: z.ZodNullable<z.ZodString>;
+  statusCode: z.ZodNullable<z.ZodNumber>;
+  outcome: z.ZodNullable<z.ZodEnum<{
+    FAILED: "FAILED";
+    SUCCEEDED: "SUCCEEDED";
+    PENDING_APPROVAL: "PENDING_APPROVAL";
+    DENIED: "DENIED";
+    DRY_RUN: "DRY_RUN";
+  }>>;
+  errorCode: z.ZodNullable<z.ZodString>;
+  traceId: z.ZodNullable<z.ZodString>;
+  idempotencyKey: z.ZodNullable<z.ZodString>;
+  approvalId: z.ZodNullable<z.ZodString>;
+  metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type AuditLog = z.infer<typeof auditLogSchema>;
+/** 감사 로그 조회 쿼리 — `GET /audit-logs` */
+export declare const auditLogListQuerySchema: z.ZodObject<{
+  from: z.ZodOptional<z.ZodString>;
+  to: z.ZodOptional<z.ZodString>;
+  actorType: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodEnum<{
+    USER: "USER";
+    AGENT: "AGENT";
+    APP: "APP";
+    TOKEN: "TOKEN";
+    SYSTEM: "SYSTEM";
+  }>>>>;
+  actorId: z.ZodOptional<z.ZodString>;
+  action: z.ZodOptional<z.ZodString>;
+  targetType: z.ZodOptional<z.ZodString>;
+  targetId: z.ZodOptional<z.ZodString>;
+  source: z.ZodOptional<z.ZodEnum<{
+    REQUEST: "REQUEST";
+    DOMAIN: "DOMAIN";
+  }>>;
+  outcome: z.ZodOptional<z.ZodEnum<{
+    FAILED: "FAILED";
+    SUCCEEDED: "SUCCEEDED";
+    PENDING_APPROVAL: "PENDING_APPROVAL";
+    DENIED: "DENIED";
+    DRY_RUN: "DRY_RUN";
+  }>>;
+  requestId: z.ZodOptional<z.ZodString>;
+  approvalId: z.ZodOptional<z.ZodString>;
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** 파싱된 조회 쿼리 (서버 측). `actorType`은 항상 배열이다 */
+export type AuditLogListParams = z.infer<typeof auditLogListQuerySchema>;
+/** 클라이언트 `auditLogs.list` 인자. `actorType`은 단일 값·배열 모두 받고 쉼표로 직렬화한다 */
+export type AuditLogListOptions = Omit<AuditLogListParams, "actorType"> & {
+  actorType?: AuditActorType | AuditActorType[];
+};
+export declare const auditLogPageSchema: z.ZodObject<{
+  items: z.ZodArray<z.ZodObject<{
+    auditId: z.ZodString;
+    occurredAt: z.ZodString;
+    source: z.ZodEnum<{
+      REQUEST: "REQUEST";
+      DOMAIN: "DOMAIN";
+    }>;
+    action: z.ZodString;
+    actor: z.ZodObject<{
+      type: z.ZodEnum<{
+        USER: "USER";
+        AGENT: "AGENT";
+        APP: "APP";
+        TOKEN: "TOKEN";
+        SYSTEM: "SYSTEM";
+      }>;
+      id: z.ZodString;
+      name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    actorRole: z.ZodNullable<z.ZodString>;
+    target: z.ZodObject<{
+      type: z.ZodString;
+      id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    requestId: z.ZodNullable<z.ZodString>;
+    method: z.ZodNullable<z.ZodString>;
+    path: z.ZodNullable<z.ZodString>;
+    statusCode: z.ZodNullable<z.ZodNumber>;
+    outcome: z.ZodNullable<z.ZodEnum<{
+      FAILED: "FAILED";
+      SUCCEEDED: "SUCCEEDED";
+      PENDING_APPROVAL: "PENDING_APPROVAL";
+      DENIED: "DENIED";
+      DRY_RUN: "DRY_RUN";
+    }>>;
+    errorCode: z.ZodNullable<z.ZodString>;
+    traceId: z.ZodNullable<z.ZodString>;
+    idempotencyKey: z.ZodNullable<z.ZodString>;
+    approvalId: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  }, z.core.$strip>>;
+  nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AuditLogPage = z.infer<typeof auditLogPageSchema>;
+export declare const agentPolicyDecisionSchema: z.ZodEnum<{
+  APPROVAL_REQUIRED: "APPROVAL_REQUIRED";
+  DENIED: "DENIED";
+  ALLOW: "ALLOW";
+}>;
+export type AgentPolicyDecision = z.infer<typeof agentPolicyDecisionSchema>;
+export declare const writePreviewSchema: z.ZodObject<{
+  operationId: z.ZodString;
+  method: z.ZodString;
+  path: z.ZodString;
+  target: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  changes: z.ZodArray<z.ZodObject<{
+    field: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+  }, z.core.$strip>>;
+  facts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type WritePreview = z.infer<typeof writePreviewSchema>;
+/** `x-sayren-dry-run: 1`을 실은 쓰기 요청의 응답(200) — 실행하지 않고 판정과 영향만 돌려준다 */
+export declare const writeDryRunResultSchema: z.ZodObject<{
+  dryRun: z.ZodLiteral<true>;
+  decision: z.ZodEnum<{
+    APPROVAL_REQUIRED: "APPROVAL_REQUIRED";
+    DENIED: "DENIED";
+    ALLOW: "ALLOW";
+  }>;
+  reason: z.ZodNullable<z.ZodString>;
+  preview: z.ZodObject<{
+    operationId: z.ZodString;
+    method: z.ZodString;
+    path: z.ZodString;
+    target: z.ZodObject<{
+      type: z.ZodString;
+      id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    changes: z.ZodArray<z.ZodObject<{
+      field: z.ZodString;
+      before: z.ZodUnknown;
+      after: z.ZodUnknown;
+    }, z.core.$strip>>;
+    facts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+export type WriteDryRunResult = z.infer<typeof writeDryRunResultSchema>;
+export declare const approvalStatusSchema: z.ZodEnum<{
+  PENDING: "PENDING";
+  FAILED: "FAILED";
+  SUCCEEDED: "SUCCEEDED";
+  EXECUTING: "EXECUTING";
+  UNKNOWN: "UNKNOWN";
+  REJECTED: "REJECTED";
+  EXPIRED: "EXPIRED";
+}>;
+export type ApprovalStatus = z.infer<typeof approvalStatusSchema>;
+export declare const approvalRequestSchema: z.ZodObject<{
+  approvalId: z.ZodString;
+  status: z.ZodEnum<{
+    PENDING: "PENDING";
+    FAILED: "FAILED";
+    SUCCEEDED: "SUCCEEDED";
+    EXECUTING: "EXECUTING";
+    UNKNOWN: "UNKNOWN";
+    REJECTED: "REJECTED";
+    EXPIRED: "EXPIRED";
+  }>;
+  operationId: z.ZodString;
+  method: z.ZodString;
+  path: z.ZodString;
+  body: z.ZodUnknown;
+  idempotencyKey: z.ZodNullable<z.ZodString>;
+  reason: z.ZodString;
+  actor: z.ZodObject<{
+    type: z.ZodEnum<{
+      USER: "USER";
+      AGENT: "AGENT";
+      APP: "APP";
+      TOKEN: "TOKEN";
+      SYSTEM: "SYSTEM";
+    }>;
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  preview: z.ZodNullable<z.ZodObject<{
+    operationId: z.ZodString;
+    method: z.ZodString;
+    path: z.ZodString;
+    target: z.ZodObject<{
+      type: z.ZodString;
+      id: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    changes: z.ZodArray<z.ZodObject<{
+      field: z.ZodString;
+      before: z.ZodUnknown;
+      after: z.ZodUnknown;
+    }, z.core.$strip>>;
+    facts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+  }, z.core.$strip>>;
+  createdAt: z.ZodString;
+  expiresAt: z.ZodString;
+  decidedAt: z.ZodNullable<z.ZodString>;
+  decidedBy: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  decisionNote: z.ZodNullable<z.ZodString>;
+  executedAt: z.ZodNullable<z.ZodString>;
+  result: z.ZodNullable<z.ZodObject<{
+    statusCode: z.ZodNumber;
+    data: z.ZodUnknown;
+    error: z.ZodNullable<z.ZodObject<{
+      code: z.ZodString;
+      message: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  approvalUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalRequest = z.infer<typeof approvalRequestSchema>;
+export declare const approvalListQuerySchema: z.ZodObject<{
+  status: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodEnum<{
+    PENDING: "PENDING";
+    FAILED: "FAILED";
+    SUCCEEDED: "SUCCEEDED";
+    EXECUTING: "EXECUTING";
+    UNKNOWN: "UNKNOWN";
+    REJECTED: "REJECTED";
+    EXPIRED: "EXPIRED";
+  }>>>>;
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ApprovalListParams = z.infer<typeof approvalListQuerySchema>;
+export type ApprovalListOptions = Omit<ApprovalListParams, "status"> & {
+  status?: ApprovalStatus | ApprovalStatus[];
+};
+export declare const approvalPageSchema: z.ZodObject<{
+  items: z.ZodArray<z.ZodObject<{
+    approvalId: z.ZodString;
+    status: z.ZodEnum<{
+      PENDING: "PENDING";
+      FAILED: "FAILED";
+      SUCCEEDED: "SUCCEEDED";
+      EXECUTING: "EXECUTING";
+      UNKNOWN: "UNKNOWN";
+      REJECTED: "REJECTED";
+      EXPIRED: "EXPIRED";
+    }>;
+    operationId: z.ZodString;
+    method: z.ZodString;
+    path: z.ZodString;
+    body: z.ZodUnknown;
+    idempotencyKey: z.ZodNullable<z.ZodString>;
+    reason: z.ZodString;
+    actor: z.ZodObject<{
+      type: z.ZodEnum<{
+        USER: "USER";
+        AGENT: "AGENT";
+        APP: "APP";
+        TOKEN: "TOKEN";
+        SYSTEM: "SYSTEM";
+      }>;
+      id: z.ZodString;
+      name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    preview: z.ZodNullable<z.ZodObject<{
+      operationId: z.ZodString;
+      method: z.ZodString;
+      path: z.ZodString;
+      target: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>;
+      changes: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+      }, z.core.$strip>>;
+      facts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    decidedBy: z.ZodNullable<z.ZodObject<{
+      id: z.ZodString;
+      name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    decisionNote: z.ZodNullable<z.ZodString>;
+    executedAt: z.ZodNullable<z.ZodString>;
+    result: z.ZodNullable<z.ZodObject<{
+      statusCode: z.ZodNumber;
+      data: z.ZodUnknown;
+      error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+      }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    approvalUrl: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+  nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalPage = z.infer<typeof approvalPageSchema>;
+export declare const approvalDecisionRequestSchema: z.ZodObject<{
+  note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalDecisionRequest = z.infer<typeof approvalDecisionRequestSchema>;
+//#endregion
 //#region src/http.d.ts
 export declare class ApiError extends Error {
   readonly status: number;
@@ -16,6 +389,32 @@ export declare class ApiError extends Error {
   /** 엔벨로프 `$.error.docs` — 이 에러 코드를 설명하는 문서 URL. 매핑이 없으면 undefined */
   docs?: string | undefined);
 }
+/** 에이전트 쓰기가 승인 대기로 보류됐다(202) */
+export declare const APPROVAL_REQUIRED_CODE = "APPROVAL_REQUIRED";
+/** 같은 멱등키의 승인 요청이 이미 끝났다(200) — 결과는 승인 요청의 `status`·`result`다 */
+export declare 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 declare class ApprovalPendingError extends Error {
+  readonly code: typeof APPROVAL_REQUIRED_CODE | typeof APPROVAL_ALREADY_DECIDED_CODE;
+  /** HTTP 상태 코드 (202·200) */
+  readonly httpStatus: number;
+  readonly approval: ApprovalRequest;
+  readonly approvalId: string;
+  /** 승인 요청 상태 */
+  readonly status: ApprovalStatus;
+  constructor(code: typeof APPROVAL_REQUIRED_CODE | typeof APPROVAL_ALREADY_DECIDED_CODE,
+  /** HTTP 상태 코드 (202·200) */
+  httpStatus: number, approval: ApprovalRequest, message: string);
+}
 type TokenSource = string | null | undefined | (() => string | null | undefined);
 type Query = Record<string, string | number | boolean | undefined>;
 export declare function buildQuery(query?: Query): string;
@@ -185,11 +584,11 @@ export declare const analyticsChannelSchema: z.ZodEnum<{
   PAID: "PAID";
   DIRECT: "DIRECT";
   CAMPAIGN: "CAMPAIGN";
+  UNKNOWN: "UNKNOWN";
   ORGANIC_SEARCH: "ORGANIC_SEARCH";
   SOCIAL: "SOCIAL";
   EMAIL: "EMAIL";
   REFERRAL: "REFERRAL";
-  UNKNOWN: "UNKNOWN";
 }>;
 export type AnalyticsChannel = z.infer<typeof analyticsChannelSchema>;
 export declare const analyticsSourceGroupBySchema: z.ZodEnum<{
@@ -219,11 +618,11 @@ export declare const analyticsSourceRowSchema: z.ZodObject<{
     PAID: "PAID";
     DIRECT: "DIRECT";
     CAMPAIGN: "CAMPAIGN";
+    UNKNOWN: "UNKNOWN";
     ORGANIC_SEARCH: "ORGANIC_SEARCH";
     SOCIAL: "SOCIAL";
     EMAIL: "EMAIL";
     REFERRAL: "REFERRAL";
-    UNKNOWN: "UNKNOWN";
   }>>;
   source: z.ZodNullable<z.ZodString>;
   medium: z.ZodNullable<z.ZodString>;
@@ -255,11 +654,11 @@ export declare const analyticsSourcesSchema: z.ZodObject<{
       PAID: "PAID";
       DIRECT: "DIRECT";
       CAMPAIGN: "CAMPAIGN";
+      UNKNOWN: "UNKNOWN";
       ORGANIC_SEARCH: "ORGANIC_SEARCH";
       SOCIAL: "SOCIAL";
       EMAIL: "EMAIL";
       REFERRAL: "REFERRAL";
-      UNKNOWN: "UNKNOWN";
     }>>;
     source: z.ZodNullable<z.ZodString>;
     medium: z.ZodNullable<z.ZodString>;
@@ -743,6 +1142,7 @@ export declare const apiTokenSchema: z.ZodObject<{
   createdAt: z.ZodString;
   expiresAt: z.ZodNullable<z.ZodString>;
   lastUsedAt: z.ZodNullable<z.ZodString>;
+  agent: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ApiToken = z.infer<typeof apiTokenSchema>;
 /** 생성 응답 — 평문 토큰은 이 응답에서 단 한 번만 노출된다 */
@@ -757,6 +1157,7 @@ export declare const apiTokenCreatedSchema: z.ZodObject<{
   createdAt: z.ZodString;
   expiresAt: z.ZodNullable<z.ZodString>;
   lastUsedAt: z.ZodNullable<z.ZodString>;
+  agent: z.ZodDefault<z.ZodBoolean>;
   token: z.ZodString;
 }, z.core.$strip>;
 export type ApiTokenCreated = z.infer<typeof apiTokenCreatedSchema>;
@@ -764,6 +1165,7 @@ export declare const apiTokenCreateRequestSchema: z.ZodObject<{
   name: z.ZodString;
   scopes: z.ZodArray<z.ZodString>;
   expiresInDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  agent: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ApiTokenCreateRequest = z.infer<typeof apiTokenCreateRequestSchema>;
 //#endregion
@@ -1067,13 +1469,13 @@ export declare const claimTypeSchema: z.ZodEnum<{
 }>;
 export type ClaimType = z.infer<typeof claimTypeSchema>;
 export declare const claimStatusSchema: z.ZodEnum<{
+  REJECTED: "REJECTED";
   REQUESTED: "REQUESTED";
   HELD: "HELD";
   COLLECTING: "COLLECTING";
   COLLECTED: "COLLECTED";
   REDELIVERING: "REDELIVERING";
   APPROVED: "APPROVED";
-  REJECTED: "REJECTED";
   COMPLETED: "COMPLETED";
   WITHDRAWN: "WITHDRAWN";
 }>;
@@ -1111,13 +1513,13 @@ export declare const claimSchema: z.ZodObject<{
     CANCEL: "CANCEL";
   }>;
   status: z.ZodEnum<{
+    REJECTED: "REJECTED";
     REQUESTED: "REQUESTED";
     HELD: "HELD";
     COLLECTING: "COLLECTING";
     COLLECTED: "COLLECTED";
     REDELIVERING: "REDELIVERING";
     APPROVED: "APPROVED";
-    REJECTED: "REJECTED";
     COMPLETED: "COMPLETED";
     WITHDRAWN: "WITHDRAWN";
   }>;
@@ -1198,13 +1600,13 @@ export declare const claimDetailSchema: z.ZodObject<{
     CANCEL: "CANCEL";
   }>;
   status: z.ZodEnum<{
+    REJECTED: "REJECTED";
     REQUESTED: "REQUESTED";
     HELD: "HELD";
     COLLECTING: "COLLECTING";
     COLLECTED: "COLLECTED";
     REDELIVERING: "REDELIVERING";
     APPROVED: "APPROVED";
-    REJECTED: "REJECTED";
     COMPLETED: "COMPLETED";
     WITHDRAWN: "WITHDRAWN";
   }>;
@@ -1254,20 +1656,20 @@ export declare const claimDetailSchema: z.ZodObject<{
   }, z.core.$strip>>;
   histories: z.ZodOptional<z.ZodArray<z.ZodObject<{
     status: z.ZodEnum<{
+      REJECTED: "REJECTED";
       REQUESTED: "REQUESTED";
       HELD: "HELD";
       COLLECTING: "COLLECTING";
       COLLECTED: "COLLECTED";
       REDELIVERING: "REDELIVERING";
       APPROVED: "APPROVED";
-      REJECTED: "REJECTED";
       COMPLETED: "COMPLETED";
       WITHDRAWN: "WITHDRAWN";
     }>;
     actor: z.ZodEnum<{
+      SYSTEM: "SYSTEM";
       BUYER: "BUYER";
       SELLER: "SELLER";
-      SYSTEM: "SYSTEM";
     }>;
     occurredAt: z.ZodString;
   }, z.core.$strip>>>;
@@ -4271,9 +4673,9 @@ export declare const invitationSchema: z.ZodObject<{
   }>;
   status: z.ZodEnum<{
     PENDING: "PENDING";
+    EXPIRED: "EXPIRED";
     CANCELED: "CANCELED";
     ACCEPTED: "ACCEPTED";
-    EXPIRED: "EXPIRED";
   }>;
   invitedBy: z.ZodString;
   expiresAt: z.ZodString;
@@ -4284,9 +4686,9 @@ export type Invitation = z.infer<typeof invitationSchema>;
 export declare const invitationListQuerySchema: z.ZodObject<{
   status: z.ZodOptional<z.ZodEnum<{
     PENDING: "PENDING";
+    EXPIRED: "EXPIRED";
     CANCELED: "CANCELED";
     ACCEPTED: "ACCEPTED";
-    EXPIRED: "EXPIRED";
   }>>;
 }, z.core.$strip>;
 /** `PATCH /v1/store/members/{userId}` 응답 — 바뀐 역할 */
@@ -4566,6 +4968,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       createdAt: string;
       expiresAt: string | null;
       lastUsedAt: string | null;
+      agent: boolean;
       token: string;
     }>;
     list: () => Promise<{
@@ -4579,6 +4982,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       createdAt: string;
       expiresAt: string | null;
       lastUsedAt: string | null;
+      agent: boolean;
     }[]>;
     revoke: (tokenId: string) => Promise<void>;
   };
@@ -5412,7 +5816,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       contents: {
         claimId: string;
         type: "RETURN" | "EXCHANGE" | "CANCEL";
-        status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
+        status: "REJECTED" | "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "COMPLETED" | "WITHDRAWN";
         orderId: string;
         orderItemId: string;
         productName: string;
@@ -5449,7 +5853,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     get: (claimId: string) => Promise<{
       claimId: string;
       type: "RETURN" | "EXCHANGE" | "CANCEL";
-      status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
+      status: "REJECTED" | "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "COMPLETED" | "WITHDRAWN";
       orderId: string;
       orderItemId: string;
       productName: string;
@@ -5482,8 +5886,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
         address2: string | null;
       } | null;
       histories?: {
-        status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
-        actor: "BUYER" | "SELLER" | "SYSTEM";
+        status: "REJECTED" | "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "COMPLETED" | "WITHDRAWN";
+        actor: "SYSTEM" | "BUYER" | "SELLER";
         occurredAt: string;
       }[] | undefined;
     }>;
@@ -5512,7 +5916,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     completeExchange: (claimId: string) => Promise<{
       claimId: string;
       type: "RETURN" | "EXCHANGE" | "CANCEL";
-      status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
+      status: "REJECTED" | "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "COMPLETED" | "WITHDRAWN";
       orderId: string;
       orderItemId: string;
       productName: string;
@@ -6027,7 +6431,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     sources: (params: AnalyticsSourcesParams) => Promise<{
       groupBy: "CHANNEL" | "SOURCE" | "CAMPAIGN" | "DEVICE";
       rows: {
-        channel: "PAID" | "DIRECT" | "CAMPAIGN" | "ORGANIC_SEARCH" | "SOCIAL" | "EMAIL" | "REFERRAL" | "UNKNOWN" | null;
+        channel: "PAID" | "DIRECT" | "CAMPAIGN" | "UNKNOWN" | "ORGANIC_SEARCH" | "SOCIAL" | "EMAIL" | "REFERRAL" | null;
         source: string | null;
         medium: string | null;
         campaign: string | null;
@@ -7173,6 +7577,244 @@ export declare function createStoreClient(options: StoreClientOptions): {
       serverErrors: number;
     }>;
   };
+  /** 감사 로그 (관리 API 쓰기의 행위자·대상·결과, 콘솔 OWNER/ADMIN, `audit:r`) */
+  auditLogs: {
+    /** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
+    list: (params?: AuditLogListOptions) => Promise<{
+      items: {
+        auditId: string;
+        occurredAt: string;
+        source: "REQUEST" | "DOMAIN";
+        action: string;
+        actor: {
+          type: "USER" | "AGENT" | "APP" | "TOKEN" | "SYSTEM";
+          id: string;
+          name: string | null;
+        };
+        actorRole: string | null;
+        target: {
+          type: string;
+          id: string | null;
+        };
+        requestId: string | null;
+        method: string | null;
+        path: string | null;
+        statusCode: number | null;
+        outcome: "FAILED" | "SUCCEEDED" | "PENDING_APPROVAL" | "DENIED" | "DRY_RUN" | null;
+        errorCode: string | null;
+        traceId: string | null;
+        idempotencyKey: string | null;
+        approvalId: string | null;
+        metadata: Record<string, unknown>;
+      }[];
+      nextCursor: string | null;
+    }>;
+  };
+  /**
+   * 승인 요청 — 에이전트의 고위험 쓰기가 202로 보류된 건. 목록·승인·거절은 콘솔 OWNER/ADMIN,
+   * 단건 조회는 요청한 토큰도 할 수 있다(상태 확인용).
+   */
+  approvalRequests: {
+    list: (params?: ApprovalListOptions) => Promise<{
+      items: {
+        approvalId: string;
+        status: "PENDING" | "FAILED" | "SUCCEEDED" | "EXECUTING" | "UNKNOWN" | "REJECTED" | "EXPIRED";
+        operationId: string;
+        method: string;
+        path: string;
+        body: unknown;
+        idempotencyKey: string | null;
+        reason: string;
+        actor: {
+          type: "USER" | "AGENT" | "APP" | "TOKEN" | "SYSTEM";
+          id: string;
+          name: string | null;
+        };
+        preview: {
+          operationId: string;
+          method: string;
+          path: string;
+          target: {
+            type: string;
+            id: string | null;
+          };
+          changes: {
+            field: string;
+            before: unknown;
+            after: unknown;
+          }[];
+          facts: Record<string, string | number | boolean | null>;
+        } | null;
+        createdAt: string;
+        expiresAt: string;
+        decidedAt: string | null;
+        decidedBy: {
+          id: string;
+          name: string | null;
+        } | null;
+        decisionNote: string | null;
+        executedAt: string | null;
+        result: {
+          statusCode: number;
+          data: unknown;
+          error: {
+            code: string;
+            message: string;
+          } | null;
+        } | null;
+        approvalUrl: string | null;
+      }[];
+      nextCursor: string | null;
+    }>;
+    get: (approvalId: string) => Promise<{
+      approvalId: string;
+      status: "PENDING" | "FAILED" | "SUCCEEDED" | "EXECUTING" | "UNKNOWN" | "REJECTED" | "EXPIRED";
+      operationId: string;
+      method: string;
+      path: string;
+      body: unknown;
+      idempotencyKey: string | null;
+      reason: string;
+      actor: {
+        type: "USER" | "AGENT" | "APP" | "TOKEN" | "SYSTEM";
+        id: string;
+        name: string | null;
+      };
+      preview: {
+        operationId: string;
+        method: string;
+        path: string;
+        target: {
+          type: string;
+          id: string | null;
+        };
+        changes: {
+          field: string;
+          before: unknown;
+          after: unknown;
+        }[];
+        facts: Record<string, string | number | boolean | null>;
+      } | null;
+      createdAt: string;
+      expiresAt: string;
+      decidedAt: string | null;
+      decidedBy: {
+        id: string;
+        name: string | null;
+      } | null;
+      decisionNote: string | null;
+      executedAt: string | null;
+      result: {
+        statusCode: number;
+        data: unknown;
+        error: {
+          code: string;
+          message: string;
+        } | null;
+      } | null;
+      approvalUrl: string | null;
+    }>;
+    /**
+     * 승인하면 서버가 원 요청을 그대로 한 번 실행한다. 응답은 실행을 기다리지 않은 `EXECUTING` 상태이고,
+     * 결과(`SUCCEEDED`·`FAILED`·`UNKNOWN`)는 `get`으로 확인한다. 두 번 눌러도 한 번만 실행한다
+     */
+    approve: (approvalId: string, body?: ApprovalDecisionRequest) => Promise<{
+      approvalId: string;
+      status: "PENDING" | "FAILED" | "SUCCEEDED" | "EXECUTING" | "UNKNOWN" | "REJECTED" | "EXPIRED";
+      operationId: string;
+      method: string;
+      path: string;
+      body: unknown;
+      idempotencyKey: string | null;
+      reason: string;
+      actor: {
+        type: "USER" | "AGENT" | "APP" | "TOKEN" | "SYSTEM";
+        id: string;
+        name: string | null;
+      };
+      preview: {
+        operationId: string;
+        method: string;
+        path: string;
+        target: {
+          type: string;
+          id: string | null;
+        };
+        changes: {
+          field: string;
+          before: unknown;
+          after: unknown;
+        }[];
+        facts: Record<string, string | number | boolean | null>;
+      } | null;
+      createdAt: string;
+      expiresAt: string;
+      decidedAt: string | null;
+      decidedBy: {
+        id: string;
+        name: string | null;
+      } | null;
+      decisionNote: string | null;
+      executedAt: string | null;
+      result: {
+        statusCode: number;
+        data: unknown;
+        error: {
+          code: string;
+          message: string;
+        } | null;
+      } | null;
+      approvalUrl: string | null;
+    }>;
+    reject: (approvalId: string, body?: ApprovalDecisionRequest) => Promise<{
+      approvalId: string;
+      status: "PENDING" | "FAILED" | "SUCCEEDED" | "EXECUTING" | "UNKNOWN" | "REJECTED" | "EXPIRED";
+      operationId: string;
+      method: string;
+      path: string;
+      body: unknown;
+      idempotencyKey: string | null;
+      reason: string;
+      actor: {
+        type: "USER" | "AGENT" | "APP" | "TOKEN" | "SYSTEM";
+        id: string;
+        name: string | null;
+      };
+      preview: {
+        operationId: string;
+        method: string;
+        path: string;
+        target: {
+          type: string;
+          id: string | null;
+        };
+        changes: {
+          field: string;
+          before: unknown;
+          after: unknown;
+        }[];
+        facts: Record<string, string | number | boolean | null>;
+      } | null;
+      createdAt: string;
+      expiresAt: string;
+      decidedAt: string | null;
+      decidedBy: {
+        id: string;
+        name: string | null;
+      } | null;
+      decisionNote: string | null;
+      executedAt: string | null;
+      result: {
+        statusCode: number;
+        data: unknown;
+        error: {
+          code: string;
+          message: string;
+        } | null;
+      } | null;
+      approvalUrl: string | null;
+    }>;
+  };
   reviews: {
     list: (params?: ReviewListParams) => Promise<{
       page: number;
@@ -7327,7 +7969,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       invitationId: string;
       email: string;
       role: "ADMIN" | "STAFF";
-      status: "PENDING" | "CANCELED" | "ACCEPTED" | "EXPIRED";
+      status: "PENDING" | "EXPIRED" | "CANCELED" | "ACCEPTED";
       invitedBy: string;
       expiresAt: string;
       createdAt: string;
@@ -7479,7 +8121,7 @@ export declare const scopeAccessSchema: z.ZodEnum<{
   rw: "rw";
 }>;
 export type ScopeAccess = z.infer<typeof scopeAccessSchema>;
-/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics·audit는 쓰기 API가 없어 `r`만 존재한다 */
 export declare const STORE_SCOPE_RESOURCES: {
   readonly product: readonly ["r", "rw"];
   readonly category: readonly ["r", "rw"];
@@ -7493,6 +8135,7 @@ export declare const STORE_SCOPE_RESOURCES: {
   readonly store: readonly ["r", "rw"];
   readonly member: readonly ["r", "rw"];
   readonly customer: readonly ["r", "rw"];
+  readonly audit: readonly ["r"];
 };
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
 export declare const storeScopeResourceSchema: z.ZodEnum<{
@@ -7508,6 +8151,7 @@ export declare const storeScopeResourceSchema: z.ZodEnum<{
   store: "store";
   member: "member";
   customer: "customer";
+  audit: "audit";
 }>;
 /** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
 export declare function isStoreScope(scope: string): boolean;
@@ -7517,8 +8161,8 @@ export declare function isStoreScope(scope: string): boolean;
  * 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
  */
 export declare const STORE_ROLE_SCOPES: {
-  readonly OWNER: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "settlement:r", "analytics:r", "webhook:rw", "store:rw", "member:rw", "customer:rw"];
-  readonly ADMIN: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "analytics:r", "webhook:rw", "store:rw", "member:rw", "customer:rw"];
+  readonly OWNER: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "settlement:r", "analytics:r", "webhook:rw", "store:rw", "member:rw", "customer:rw", "audit:r"];
+  readonly ADMIN: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "analytics:r", "webhook:rw", "store:rw", "member:rw", "customer:rw", "audit:r"];
   readonly STAFF: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "customer:r"];
 };
 //#endregion
@@ -7710,6 +8354,56 @@ export interface DeliveryQuoteInput {
  */
 export declare function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote;
 //#endregion
+//#region src/schemas/telemetry.d.ts
+/**
+ * MCP 도구 호출 계측 (`POST /v1/telemetry/mcp`, 이슈 #34).
+ *
+ * `@sayren/mcp`가 `verify_storefront` 같은 도구를 돌린 뒤 결과 요약을 보낸다. 목적은 하나다 —
+ * AI가 만든 스토어프론트가 **처음에** 규칙을 통과하는지, 통과하지 못하면 어떤 규칙에서 막히는지를
+ * 세는 것이다. 그 숫자가 규칙과 안내를 고치는 근거가 된다.
+ *
+ * **보내지 않는 것**: 파일 경로·소스 코드·위반 상세(`detail`)·토큰·사람 식별자. 규칙 id와 개수뿐이다.
+ * 테넌트는 요청 토큰이 정한다(본문에 스토어 id가 없다). 옵트아웃은 클라이언트의 `SAYREN_TELEMETRY=0`이다.
+ *
+ * 알 수 없는 키는 저장하지 않고 버린다(`.strict()`를 쓰지 않는다) — 새 버전 클라이언트가 필드를
+ * 하나 더 실었다고 계측 전체가 400으로 날아가면 그 버전의 숫자가 통째로 빈다.
+ */
+/** 규칙 하나의 검사 결과. `ruleId`는 늘어나므로 enum이 아니라 형식만 좁힌다 */
+export declare const mcpRuleResultSchema: z.ZodObject<{
+  ruleId: z.ZodString;
+  status: z.ZodEnum<{
+    pass: "pass";
+    violation: "violation";
+  }>;
+  count: z.ZodNumber;
+}, z.core.$strip>;
+export type McpRuleResult = z.infer<typeof mcpRuleResultSchema>;
+/**
+ * 한 번에 실을 수 있는 규칙 결과 수 — 규칙 수(현재 16개)의 두 배까지다.
+ *
+ * 규칙 수 수준으로 좁게 둔다. 이 배열이 그대로 `mcp_tool_events.results` jsonb가 되므로 상한이
+ * 넉넉하면 한 행의 크기가 그만큼 커지고, 집계가 그 jsonb를 펼친다.
+ */
+export declare const MCP_TELEMETRY_MAX_RESULTS = 32;
+export declare const mcpToolEventSchema: z.ZodObject<{
+  tool: z.ZodString;
+  clientVersion: z.ZodOptional<z.ZodString>;
+  sessionId: z.ZodString;
+  attempt: z.ZodNumber;
+  durationMs: z.ZodOptional<z.ZodNumber>;
+  ok: z.ZodBoolean;
+  checkedFiles: z.ZodNumber;
+  results: z.ZodArray<z.ZodObject<{
+    ruleId: z.ZodString;
+    status: z.ZodEnum<{
+      pass: "pass";
+      violation: "violation";
+    }>;
+    count: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpToolEvent = z.infer<typeof mcpToolEventSchema>;
+//#endregion
 //#region src/schemas/webhook-event.d.ts
 export declare const orderWebhookEventDataSchema: z.ZodObject<{
   orderId: z.ZodString;
@@ -7736,13 +8430,13 @@ export declare const claimWebhookEventDataSchema: z.ZodObject<{
     CANCEL: "CANCEL";
   }>;
   status: z.ZodEnum<{
+    REJECTED: "REJECTED";
     REQUESTED: "REQUESTED";
     HELD: "HELD";
     COLLECTING: "COLLECTING";
     COLLECTED: "COLLECTED";
     REDELIVERING: "REDELIVERING";
     APPROVED: "APPROVED";
-    REJECTED: "REJECTED";
     COMPLETED: "COMPLETED";
     WITHDRAWN: "WITHDRAWN";
   }>;
@@ -7814,13 +8508,13 @@ export declare const claimWebhookEventSchema: z.ZodObject<{
       CANCEL: "CANCEL";
     }>;
     status: z.ZodEnum<{
+      REJECTED: "REJECTED";
       REQUESTED: "REQUESTED";
       HELD: "HELD";
       COLLECTING: "COLLECTING";
       COLLECTED: "COLLECTED";
       REDELIVERING: "REDELIVERING";
       APPROVED: "APPROVED";
-      REJECTED: "REJECTED";
       COMPLETED: "COMPLETED";
       WITHDRAWN: "WITHDRAWN";
     }>;
@@ -7910,13 +8604,13 @@ export declare const webhookEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       CANCEL: "CANCEL";
     }>;
     status: z.ZodEnum<{
+      REJECTED: "REJECTED";
       REQUESTED: "REQUESTED";
       HELD: "HELD";
       COLLECTING: "COLLECTING";
       COLLECTED: "COLLECTED";
       REDELIVERING: "REDELIVERING";
       APPROVED: "APPROVED";
-      REJECTED: "REJECTED";
       COMPLETED: "COMPLETED";
       WITHDRAWN: "WITHDRAWN";
     }>;