@sayren/store-sdk 0.12.0 → 0.14.0

package/src/schemas/audit.ts

@@ -0,0 +1,255 @@
+import { z } from "zod";
+
+/**
+ * 감사 로그와 승인 요청 — `/v1/audit-logs`, `/v1/approval-requests` (이슈 #36).
+ *
+ * 관리 API 쓰기(`/v1/**`의 GET 외 요청)는 모두 요청 단위 기록(`source: REQUEST`) 한 줄을 남긴다. 환불·직권취소 같은
+ * 도메인 동작은 그 안에서 변경 전후를 담은 기록(`source: DOMAIN`)을 따로 남기고 `requestId`로 요청 기록과 이어진다.
+ */
+
+export const auditActorTypeSchema = z
+  .enum(["USER", "AGENT", "APP", "TOKEN", "SYSTEM"])
+  .describe(
+    "행위자 유형. `USER`=콘솔 사용자, `AGENT`=AI 에이전트(MCP·에이전트용 API 토큰), `APP`=앱(OAuth 클라이언트·M2M), " +
+      "`TOKEN`=API 토큰, `SYSTEM`=자동화(주기 잡)",
+  );
+export type AuditActorType = z.infer<typeof auditActorTypeSchema>;
+
+export 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"),
+});
+export type AuditActor = z.infer<typeof auditActorSchema>;
+
+export const auditLogSourceSchema = z
+  .enum(["REQUEST", "DOMAIN"])
+  .describe(
+    "기록 단위. `REQUEST`=관리 API 쓰기 요청 한 건, `DOMAIN`=환불·취소 같은 도메인 동작의 상세",
+  );
+export type AuditLogSource = z.infer<typeof auditLogSourceSchema>;
+
+export 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`)이라 실행하지 않음",
+  );
+export type AuditLogOutcome = z.infer<typeof auditLogOutcomeSchema>;
+
+export 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`)를 싣는다",
+    ),
+});
+export type AuditLog = z.infer<typeof auditLogSchema>;
+
+/** 쉼표 구분 목록 쿼리 → 배열 */
+function commaList<T extends z.ZodType<string, string>>(item: T) {
+  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` */
+export 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)"),
+});
+/** 파싱된 조회 쿼리 (서버 측). `actorType`은 항상 배열이다 */
+export type AuditLogListParams = z.infer<typeof auditLogListQuerySchema>;
+
+/** 클라이언트 `auditLogs.list` 인자. `actorType`은 단일 값·배열 모두 받고 쉼표로 직렬화한다 */
+export type AuditLogListOptions = Omit<AuditLogListParams, "actorType"> & {
+  actorType?: AuditActorType | AuditActorType[];
+};
+
+export const auditLogPageSchema = z.object({
+  items: z.array(auditLogSchema),
+  nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null"),
+});
+export type AuditLogPage = z.infer<typeof auditLogPageSchema>;
+
+// ─── 에이전트 쓰기 정책·영향 미리보기 ──────────────────────────
+
+export const agentPolicyDecisionSchema = z
+  .enum(["ALLOW", "APPROVAL_REQUIRED", "DENIED"])
+  .describe(
+    "에이전트 쓰기 판정. `ALLOW`=바로 실행, `APPROVAL_REQUIRED`=콘솔 승인 뒤 실행, `DENIED`=에이전트는 실행할 수 없음",
+  );
+export type AgentPolicyDecision = z.infer<typeof agentPolicyDecisionSchema>;
+
+const previewValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+export 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("영향 요약 (예: 취소 수량·주문상품 금액·예상 환불액). 오퍼레이션마다 다르다"),
+});
+export type WritePreview = z.infer<typeof writePreviewSchema>;
+
+/** `x-sayren-dry-run: 1`을 실은 쓰기 요청의 응답(200) — 실행하지 않고 판정과 영향만 돌려준다 */
+export const writeDryRunResultSchema = z.object({
+  dryRun: z.literal(true),
+  decision: agentPolicyDecisionSchema,
+  reason: z.string().nullable().describe("승인 필요·거부 사유. `ALLOW`면 null"),
+  preview: writePreviewSchema,
+});
+export type WriteDryRunResult = z.infer<typeof writeDryRunResultSchema>;
+
+// ─── 승인 요청 ───────────────────────────────────────────────
+
+export const approvalStatusSchema = z
+  .enum(["PENDING", "EXECUTING", "SUCCEEDED", "FAILED", "UNKNOWN", "REJECTED", "EXPIRED"])
+  .describe(
+    "승인 요청 상태. `PENDING` 승인 대기 → 승인하면 `EXECUTING`(원 요청 실행 중) → `SUCCEEDED`·`FAILED`(원 요청의 응답 기준), " +
+      "거절하면 `REJECTED`, 기한이 지나면 `EXPIRED`. 실행 응답을 받지 못했으면(타임아웃·서버 종료) `UNKNOWN`이다 — " +
+      "서버가 감사 로그로 결과를 확정하면 `SUCCEEDED`·`FAILED`로 바뀌고, 확정하지 못하면 `UNKNOWN`에 남는다. " +
+      "`UNKNOWN`은 다시 실행하지 않는다(이미 실행됐을 수 있다)",
+  );
+export type ApprovalStatus = z.infer<typeof approvalStatusSchema>;
+
+export 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"),
+});
+export type ApprovalRequest = z.infer<typeof approvalRequestSchema>;
+
+export 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)"),
+});
+export type ApprovalListParams = z.infer<typeof approvalListQuerySchema>;
+export type ApprovalListOptions = Omit<ApprovalListParams, "status"> & {
+  status?: ApprovalStatus | ApprovalStatus[];
+};
+
+export const approvalPageSchema = z.object({
+  items: z.array(approvalRequestSchema),
+  nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null"),
+});
+export type ApprovalPage = z.infer<typeof approvalPageSchema>;
+
+export const approvalDecisionRequestSchema = z.object({
+  note: z.string().trim().max(500).optional().describe("승인·거절 메모 (최대 500자)"),
+});
+export type ApprovalDecisionRequest = z.infer<typeof approvalDecisionRequestSchema>;

package/src/schemas/auth.ts

@@ -65,6 +65,12 @@ export const apiTokenSchema = z.object({
   createdAt: z.string(),
   expiresAt: z.string().nullable(),
   lastUsedAt: z.string().nullable(),
+  agent: z
+    .boolean()
+    .default(false)
+    .describe(
+      "AI 에이전트(MCP)용 토큰인가. true면 이 토큰의 쓰기는 행위자 `AGENT`로 기록되고 에이전트 쓰기 정책(승인 필요·거부)을 따른다",
+    ),
 });
 export type ApiToken = z.infer<typeof apiTokenSchema>;
 
@@ -77,5 +83,7 @@ export const apiTokenCreateRequestSchema = z.object({
   scopes: z.array(z.string()).min(1),
   /** 일 단위 만료. null = 무기한, 생략 = 90일 */
   expiresInDays: z.number().int().nullable().optional(),
+  /** AI 에이전트(MCP)용 토큰. 생략 = false. 발급 뒤에는 바꿀 수 없다 */
+  agent: z.boolean().optional(),
 });
 export type ApiTokenCreateRequest = z.infer<typeof apiTokenCreateRequestSchema>;

package/src/schemas/scope.ts

@@ -14,7 +14,7 @@ export const scopeAccessSchema = z
   .describe("접근 수준. `r`=읽기, `rw`=읽기+쓰기(r을 함의)");
 export type ScopeAccess = z.infer<typeof scopeAccessSchema>;
 
-/** 리소스별로 부여 가능한 접근 수준. settlement·analytics는 쓰기 API가 없어 `r`만 존재한다 */
+/** 리소스별로 부여 가능한 접근 수준. settlement·analytics·audit는 쓰기 API가 없어 `r`만 존재한다 */
 export const STORE_SCOPE_RESOURCES = {
   product: ["r", "rw"],
   category: ["r", "rw"],
@@ -28,6 +28,7 @@ export const STORE_SCOPE_RESOURCES = {
   store: ["r", "rw"],
   member: ["r", "rw"],
   customer: ["r", "rw"],
+  audit: ["r"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -63,6 +64,7 @@ export const STORE_ROLE_SCOPES = {
     "store:rw",
     "member:rw",
     "customer:rw",
+    "audit:r",
   ],
   ADMIN: [
     "product:rw",
@@ -76,6 +78,7 @@ export const STORE_ROLE_SCOPES = {
     "store:rw",
     "member:rw",
     "customer:rw",
+    "audit:r",
   ],
   STAFF: [
     "product:rw",

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