@sayren/store-sdk 0.1.0

package/src/http.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+
+/** 표준 엔벨로프의 $.error 상세 */
+export const errorDetailSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  traceId: z.string().optional(),
+  /**
+   * 에러 코드별 보조 데이터(선택). 예: 관리 API `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의
+   * `{ conditions: LiveGateCondition[] }`. 형태는 에러 코드마다 다르므로 소비측이 코드별 스키마로 다시 파싱한다
+   */
+  details: z.record(z.string(), z.unknown()).optional().catch(undefined),
+});
+
+/** 표준 응답 엔벨로프 — $.meta / $.data / $.error */
+export const envelopeSchema = z.object({
+  meta: z.object({
+    status: z.number(),
+    code: z.string(),
+    message: z.string(),
+    isSuccess: z.boolean(),
+  }),
+  data: z.unknown().optional(),
+  /** 구형 필드 — data로 개명되기 전 응답과의 전환기 호환 */
+  content: z.unknown().optional(),
+  error: errorDetailSchema.nullable(),
+});
+
+export type ApiErrorBody = z.infer<typeof errorDetailSchema>;
+
+/** OAuth 프로토콜 표면의 평면 에러 (RFC 6749 §5.2, RFC 7591 §3.2.2) */
+const oauthErrorSchema = z.object({
+  error: z.string(),
+  error_description: z.string().optional(),
+});
+
+/** 표준 엔벨로프면 $.data(구형 $.content)를, 아니면(평면 응답) 본문 전체를 반환 */
+export function unwrapData(json: unknown): unknown {
+  const envelope = envelopeSchema.safeParse(json);
+  if (!envelope.success) return json;
+  return envelope.data.data ?? envelope.data.content ?? null;
+}
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    message: string,
+    public readonly traceId?: string,
+    public readonly body?: unknown,
+    /** 엔벨로프 `$.error.details` — 에러 코드별 보조 데이터. 없으면 undefined */
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/**
+ * 에러 응답 본문 → ApiError 구성 (에러 형태의 단일 원천).
+ * 표준 엔벨로프($.error) 우선, 구형 평면 에러({ code, message }), OAuth 평면 에러
+ * ({ error, error_description } → code=error, message=error_description) 순으로 폴백하고,
+ * 모두 아니면 UNKNOWN. createHttp의 send와 세션(userinfo 등 raw fetch 경로)이 동일한 에러 모양을 내도록 공유한다.
+ */
+export function toApiError(status: number, raw: unknown): ApiError {
+  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);
+  }
+  const oauth = envelope.success ? null : oauthErrorSchema.safeParse(raw).data;
+  if (oauth) {
+    return new ApiError(
+      status,
+      oauth.error,
+      oauth.error_description ?? oauth.error,
+      undefined,
+      raw,
+    );
+  }
+  return new ApiError(status, "UNKNOWN", `HTTP ${status}`, undefined, raw);
+}
+
+/**
+ * 경로 템플릿 태그 — 보간 값(경로 파라미터)마다 encodeURIComponent를 적용한다.
+ * `/`·`?`·`#` 등이 섞인 id가 다른 경로·쿼리로 해석되지 않게 한다. 예: path`/products/${id}`
+ */
+export function path(strings: TemplateStringsArray, ...params: Array<string | number>): string {
+  return strings.reduce(
+    (acc, part, i) => acc + part + (i < params.length ? encodeURIComponent(String(params[i])) : ""),
+    "",
+  );
+}
+
+export type TokenSource = string | null | undefined | (() => string | null | undefined);
+
+export function resolveToken(source: TokenSource): string | null {
+  const value = typeof source === "function" ? source() : source;
+  return value ?? null;
+}
+
+export interface HttpOptions {
+  baseUrl: string;
+  fetch?: typeof globalThis.fetch;
+  headers?: () => Record<string, string>;
+  onResponse?: (response: Response) => void;
+  /**
+   * 401 시 호출 — 세션을 갱신하고 true면 요청을 **1회 재시도**한다(headers 콜백이 새 토큰을 읽는다).
+   * false거나 재시도 후에도 401이면 onUnauthorized로 넘어간다.
+   */
+  refresh?: () => Promise<boolean>;
+  /** 복구 불가능한 401(갱신 실패/재시도 후에도 401) 시 호출 — 재로그인 유도용 */
+  onUnauthorized?: () => void;
+}
+
+export type Query = Record<string, string | number | boolean | undefined>;
+
+export function buildQuery(query?: Query): string {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+
+export interface RequestOptions {
+  query?: Query;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export interface Http {
+  request<T>(
+    method: string,
+    path: string,
+    schema: z.ZodType<T>,
+    options?: RequestOptions,
+  ): Promise<T>;
+  requestVoid(method: string, path: string, options?: RequestOptions): Promise<void>;
+}
+
+export function createHttp(options: HttpOptions): Http {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+
+  async function send(
+    method: string,
+    path: string,
+    request?: RequestOptions,
+    retried = false,
+  ): Promise<Response> {
+    const url = `${options.baseUrl}${path}${buildQuery(request?.query)}`;
+    const headers: Record<string, string> = {
+      ...(request?.body !== undefined ? { "content-type": "application/json" } : {}),
+      ...options.headers?.(),
+      ...request?.headers,
+    };
+    const response = await fetchFn(url, {
+      method,
+      headers,
+      body: request?.body !== undefined ? JSON.stringify(request.body) : undefined,
+    });
+    options.onResponse?.(response);
+    // 401 → 세션 갱신 후 1회 재시도. headers 콜백이 갱신된 토큰을 읽으므로 재시도는 새 토큰으로 나간다.
+    if (response.status === 401 && !retried && options.refresh) {
+      if (await options.refresh()) return send(method, path, request, true);
+    }
+    if (!response.ok) {
+      if (response.status === 401) options.onUnauthorized?.();
+      const raw = await response.json().catch(() => null);
+      throw toApiError(response.status, raw);
+    }
+    return response;
+  }
+
+  return {
+    async request<T>(
+      method: string,
+      path: string,
+      schema: z.ZodType<T>,
+      request?: RequestOptions,
+    ): Promise<T> {
+      const response = await send(method, path, request);
+      const json: unknown = await response.json();
+      return schema.parse(unwrapData(json));
+    },
+    async requestVoid(method: string, path: string, request?: RequestOptions): Promise<void> {
+      await send(method, path, request);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export type { StoreClient, StoreClientOptions } from "./client";
+export { createStoreClient } from "./client";
+export type { Query, TokenSource } from "./http";
+export { ApiError, buildQuery } from "./http";
+export {
+  buildAuthorizeUrl,
+  createPkcePair,
+  exchangeAuthorizationCode,
+  exchangeStoreTokenViaOAuth,
+  type OAuthTokenResponse,
+  oauthTokenResponseSchema,
+  refreshUserToken,
+} from "./oauth";
+export * from "./schemas/api-client";
+export * from "./schemas/api-log";
+export * from "./schemas/auth";
+export * from "./schemas/category";
+export * from "./schemas/claim";
+export * from "./schemas/common";
+export * from "./schemas/misc";
+export * from "./schemas/order";
+export * from "./schemas/payment";
+export * from "./schemas/product";
+export * from "./schemas/scope";
+export * from "./schemas/store";
+export * from "./schemas/upload";
+export * from "./schemas/webhook-event";
+export {
+  type AuthorizeOptions,
+  createStoreSession,
+  type SessionStorage,
+  STORE_SESSION_KEYS,
+  type StoreSession,
+  type StoreSessionOptions,
+} from "./session";

package/src/oauth.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { base64UrlFromBytes } from "./base64";
+import { unwrapData } from "./http";
+
+/**
+ * OAuth 2.1 브라우저 플로우 헬퍼 (authorization_code + PKCE).
+ * Web Crypto만 사용 — 브라우저/Node 모두에서 동작하며 **시크릿을 다루지 않는다**.
+ */
+
+/** RFC 6749 §5.1 토큰 응답 (+ RFC 8693 확장 멤버 허용) */
+export const oauthTokenResponseSchema = z
+  .object({
+    access_token: z.string(),
+    token_type: z.literal("Bearer"),
+    expires_in: z.number().int(),
+    scope: z.string().optional(),
+    refresh_token: z.string().optional(),
+  })
+  .loose();
+export type OAuthTokenResponse = z.infer<typeof oauthTokenResponseSchema>;
+
+/** PKCE 페어 생성 — verifier(43~128자) + S256 challenge */
+export async function createPkcePair(): Promise<{ verifier: string; challenge: string }> {
+  const random = new Uint8Array(48);
+  crypto.getRandomValues(random);
+  const verifier = base64UrlFromBytes(random); // 64자
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64UrlFromBytes(new Uint8Array(digest)) };
+}
+
+export interface AuthorizeUrlOptions {
+  /** 예: https://api.sayren.app/v1 (베이스 URL — /oauth2/authorize가 덧붙는다) */
+  baseUrl: string;
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  codeChallenge: string;
+  /** 생략 시 서버 기본(stores:read). refresh가 필요하면 offline_access 포함 */
+  scope?: string;
+}
+
+/** authorize 엔드포인트 URL 구성 — 브라우저는 이 URL로 이동(top-level navigation) */
+export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
+  const url = new URL(`${options.baseUrl}/oauth2/authorize`);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("state", options.state);
+  url.searchParams.set("code_challenge", options.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (options.scope) url.searchParams.set("scope", options.scope);
+  return url.toString();
+}
+
+async function tokenRequest(
+  baseUrl: string,
+  form: Record<string, string>,
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<OAuthTokenResponse> {
+  const response = await fetchFn(`${baseUrl}/oauth2/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(form).toString(),
+  });
+  const json: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    const body = json as { error?: string; error_description?: string } | null;
+    throw new Error(body?.error_description ?? body?.error ?? `HTTP ${response.status}`);
+  }
+  return oauthTokenResponseSchema.parse(unwrapData(json));
+}
+
+/** 콜백에서 받은 code를 userToken으로 교환 (PKCE verifier 동반) */
+export async function exchangeAuthorizationCode(options: {
+  baseUrl: string;
+  clientId: string;
+  redirectUri: string;
+  code: string;
+  codeVerifier: string;
+  fetch?: typeof globalThis.fetch;
+}): Promise<OAuthTokenResponse> {
+  return tokenRequest(
+    options.baseUrl,
+    {
+      grant_type: "authorization_code",
+      code: options.code,
+      redirect_uri: options.redirectUri,
+      client_id: options.clientId,
+      code_verifier: options.codeVerifier,
+    },
+    options.fetch,
+  );
+}
+
+/** refresh grant (rotation — 응답의 새 refresh_token으로 반드시 교체 저장할 것) */
+export async function refreshUserToken(options: {
+  baseUrl: string;
+  clientId: string;
+  refreshToken: string;
+  fetch?: typeof globalThis.fetch;
+}): Promise<OAuthTokenResponse> {
+  return tokenRequest(
+    options.baseUrl,
+    {
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+      client_id: options.clientId,
+    },
+    options.fetch,
+  );
+}
+
+/** userToken → storeToken 교환 (RFC 8693 token-exchange grant) */
+export async function exchangeStoreTokenViaOAuth(options: {
+  baseUrl: string;
+  clientId: string;
+  userToken: string;
+  storeId: string;
+  fetch?: typeof globalThis.fetch;
+}): Promise<OAuthTokenResponse & { storeId?: string; role?: string }> {
+  return tokenRequest(
+    options.baseUrl,
+    {
+      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+      subject_token: options.userToken,
+      subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
+      audience: options.storeId,
+      client_id: options.clientId,
+    },
+    options.fetch,
+  );
+}

package/src/schemas/api-client.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+/**
+ * 앱(OAuth 클라이언트) 관리 — `/v1/store/api-clients` (auth-spec 부록 B-13).
+ * 등록은 DCR(`POST /v1/oauth2/register`, RFC 7591)이 담당하고, 이 스키마는 등록 이후의
+ * 목록·상세·시크릿 재발급·비활성화 응답 계약이다. 시크릿 해시는 어떤 응답에도 포함되지 않는다.
+ */
+
+export const apiClientTypeSchema = z
+  .enum(["public", "confidential"])
+  .describe(
+    "클라이언트 유형. `public`=시크릿 없음(PKCE 로그인용), `confidential`=시크릿 보유(서버 간 연동용)",
+  );
+export type ApiClientType = z.infer<typeof apiClientTypeSchema>;
+
+export const apiClientStatusSchema = z
+  .enum(["ACTIVE", "REVOKED"])
+  .describe("상태. `REVOKED`는 비활성화된 클라이언트이며 다시 활성화할 수 없다");
+export type ApiClientStatus = z.infer<typeof apiClientStatusSchema>;
+
+export const apiClientSchema = z.object({
+  clientId: z.string().describe("클라이언트 ID (`client_id`)"),
+  name: z.string().describe("클라이언트 이름 (`client_name`)"),
+  type: apiClientTypeSchema,
+  status: apiClientStatusSchema,
+  redirectUris: z
+    .array(z.string())
+    .describe("authorization_code 리다이렉트 URI 허용 목록 (정확 일치)"),
+  scopes: z.array(z.string()).describe("클라이언트가 요청할 수 있는 최대 스코프"),
+  grantTypes: z.array(z.string()).describe("허용된 grant_type 목록"),
+  secretPrefix: z
+    .string()
+    .nullable()
+    .describe(
+      "시크릿 앞부분(식별용, 인증에 사용할 수 없음). public 클라이언트와 시크릿 앞부분이 기록되기 전에 등록된 클라이언트는 null",
+    ),
+  createdBy: z
+    .string()
+    .nullable()
+    .describe("등록자 userId. 등록자 기록이 도입되기 전에 등록된 클라이언트는 null"),
+  createdByName: z.string().nullable().describe("등록자 이름 (표시용). 계정이 없으면 null"),
+  createdByEmail: z.string().nullable().describe("등록자 이메일 (표시용). 계정이 없으면 null"),
+  createdAt: z.string().describe("등록 일시 (ISO 8601)"),
+  revokedAt: z.string().nullable().describe("비활성화 일시 (ISO 8601). 활성 상태면 null"),
+});
+export type ApiClient = z.infer<typeof apiClientSchema>;
+
+/** 시크릿 재발급 응답 — 평문 시크릿은 이 응답에서 단 한 번만 노출된다 */
+export const apiClientSecretRotatedSchema = apiClientSchema.extend({
+  clientSecret: z
+    .string()
+    .describe("새 클라이언트 시크릿 평문. 이 응답에서만 노출되며 다시 조회할 수 없다"),
+});
+export type ApiClientSecretRotated = z.infer<typeof apiClientSecretRotatedSchema>;
+
+export const apiClientListQuerySchema = z.object({
+  status: apiClientStatusSchema.optional().describe("상태 필터. 생략하면 전체"),
+});
+export type ApiClientListParams = z.infer<typeof apiClientListQuerySchema>;
+
+/**
+ * Dynamic Client Registration 요청 (RFC 7591 §2, auth-spec §12) — `POST /v1/oauth2/register`.
+ * OAuth 프로토콜 표면이라 필드명이 snake_case이고 응답·등록 오류는 평면 JSON이다.
+ * 생략한 필드는 서버 기본값을 따른다(SDK가 기본값을 채워 보내지 않는다).
+ */
+export const oauthClientRegistrationRequestSchema = z.object({
+  client_name: z.string().min(1).max(80).describe("클라이언트 이름 (1~80자)"),
+  token_endpoint_auth_method: z
+    .enum(["none", "client_secret_basic"])
+    .optional()
+    .describe(
+      "토큰 엔드포인트 인증 방식. `none`=public(시크릿 없음), `client_secret_basic`=confidential. 생략하면 `client_secret_basic`",
+    ),
+  redirect_uris: z
+    .array(z.string())
+    .max(10)
+    .optional()
+    .describe(
+      "리다이렉트 URI 목록(최대 10개). authorization_code에는 필수이며 https(개발용 루프백 http 제외)만 허용",
+    ),
+  grant_types: z
+    .array(
+      z.enum([
+        "authorization_code",
+        "refresh_token",
+        "client_credentials",
+        "urn:ietf:params:oauth:grant-type:token-exchange",
+      ]),
+    )
+    .min(1)
+    .optional()
+    .describe("허용할 grant_type 목록. 생략하면 `client_credentials`"),
+  scope: z
+    .string()
+    .optional()
+    .describe(
+      "공백 구분 스코프. 등록자 보유 스코프 이내여야 한다. 생략하면 confidential은 등록자 스코프, public은 `stores:read`",
+    ),
+});
+export type OAuthClientRegistrationRequest = z.infer<typeof oauthClientRegistrationRequestSchema>;
+
+/** Dynamic Client Registration 응답 (RFC 7591 §3.2.1) — client_secret은 이 응답에서만 노출된다 */
+export const oauthClientRegistrationResponseSchema = z.object({
+  client_id: z.string().describe("발급된 클라이언트 ID"),
+  client_secret: z
+    .string()
+    .optional()
+    .describe("클라이언트 시크릿 평문. confidential만 있으며 이 응답에서만 노출된다"),
+  client_secret_expires_at: z
+    .number()
+    .int()
+    .optional()
+    .describe("시크릿 만료 시각(epoch 초). 0은 만료 없음. confidential만 있다"),
+  client_id_issued_at: z.number().int().describe("발급 시각 (epoch 초)"),
+  client_name: z.string(),
+  token_endpoint_auth_method: z.enum(["none", "client_secret_basic"]),
+  redirect_uris: z.array(z.string()),
+  grant_types: z.array(z.string()),
+  scope: z.string().describe("부여된 스코프 (공백 구분)"),
+});
+export type OAuthClientRegistrationResponse = z.infer<typeof oauthClientRegistrationResponseSchema>;

package/src/schemas/api-log.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+
+/**
+ * API 로그 — `/v1/api-logs`. 스토어가 해석된 관리 API(`/v1/**`) 요청을 7일간 보관한다.
+ * 인증에 실패해 스토어를 알 수 없는 요청(401 등)은 기록되지 않는다.
+ * Authorization·쿠키 헤더, 요청 본문, 개인정보는 저장하지 않는다.
+ */
+
+export const apiLogPrincipalTypeSchema = z
+  .enum(["USER", "PAT", "CLIENT"])
+  .describe("호출 주체 유형. `USER`=콘솔 사용자, `PAT`=API 토큰, `CLIENT`=앱(OAuth 클라이언트)");
+export type ApiLogPrincipalType = z.infer<typeof apiLogPrincipalTypeSchema>;
+
+export const apiLogPrincipalSchema = z.object({
+  type: apiLogPrincipalTypeSchema,
+  id: z.string().describe("호출 주체 ID. `USER`=userId, `PAT`=API 토큰 ID, `CLIENT`=clientId"),
+  name: z
+    .string()
+    .nullable()
+    .describe("기록 시점의 표시 이름 (사용자 이름·API 토큰 이름·앱 이름). 알 수 없으면 null"),
+});
+export type ApiLogPrincipal = z.infer<typeof apiLogPrincipalSchema>;
+
+export const apiLogErrorSchema = z.object({
+  code: z.string().describe("에러 코드. 에러 응답 `error.code`와 같다"),
+  message: z.string().describe("에러 메시지. 에러 응답 `error.message`와 같다"),
+});
+export type ApiLogError = z.infer<typeof apiLogErrorSchema>;
+
+export const apiLogSchema = z.object({
+  logId: z.string().describe("로그 ID"),
+  occurredAt: z.string().describe("요청 일시 (ISO 8601)"),
+  method: z.string().describe("HTTP 메서드"),
+  path: z
+    .string()
+    .describe(
+      "요청 경로와 쿼리. token·secret·code·password·email·phone 등 민감한 쿼리 값은 `***`로 가린다",
+    ),
+  statusCode: z.number().int().describe("응답 HTTP 상태 코드"),
+  latencyMs: z.number().int().min(0).describe("처리 시간(ms)"),
+  principal: apiLogPrincipalSchema,
+  traceId: z.string().nullable().describe("추적 ID. 에러 응답의 `error.traceId`와 같다"),
+  error: apiLogErrorSchema.nullable().describe("에러 응답 요약. 4xx·5xx일 때만 값이 있다"),
+});
+export type ApiLog = z.infer<typeof apiLogSchema>;
+
+export const apiLogStatusFilterSchema = z
+  .enum(["2xx", "3xx", "4xx", "5xx", "error"])
+  .describe("응답 상태 필터. `error`는 4xx·5xx 전체");
+export type ApiLogStatusFilter = z.infer<typeof apiLogStatusFilterSchema>;
+
+/** API 로그 조회 쿼리 — `GET /api-logs` */
+export const apiLogListQuerySchema = z.object({
+  from: z.string().optional().describe("조회 시작 일시 (ISO 8601, 포함). 보관 기간은 7일이다"),
+  to: z.string().optional().describe("조회 종료 일시 (ISO 8601, 미포함)"),
+  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("경로 부분 일치 검색어"),
+  cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 가장 최신부터"),
+  limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50)"),
+});
+/** 파싱된 조회 쿼리 (서버 측). `principalType`은 항상 배열이다 */
+export type ApiLogListParams = z.infer<typeof apiLogListQuerySchema>;
+
+/** 클라이언트 `apiLogs.list` 인자. `principalType`은 단일 값·배열 모두 받고 쉼표로 직렬화한다 */
+export type ApiLogListOptions = Omit<ApiLogListParams, "principalType"> & {
+  principalType?: ApiLogPrincipalType | ApiLogPrincipalType[];
+};
+
+/** API 로그 목록 응답 (최신순, 커서 페이지네이션) */
+export const apiLogPageSchema = z.object({
+  items: z.array(apiLogSchema),
+  nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null"),
+});
+export type ApiLogPage = z.infer<typeof apiLogPageSchema>;
+
+/**
+ * API 로그 요약 — `GET /api-logs/summary`. 연동 트래픽(호출 주체 `PAT`·`CLIENT`)만 집계하며
+ * 콘솔 사용자(`USER`) 요청은 제외한다
+ */
+export const apiLogSummarySchema = z.object({
+  windowHours: z.number().int().describe("집계 구간(시간). 최근 24시간"),
+  total: z
+    .number()
+    .int()
+    .min(0)
+    .describe("구간 내 연동 요청 수 (호출 주체 `PAT`·`CLIENT`, 콘솔 사용자 제외)"),
+  errors: z.number().int().min(0).describe("구간 내 연동 요청 중 4xx·5xx 응답 수"),
+  serverErrors: z.number().int().min(0).describe("구간 내 연동 요청 중 5xx 응답 수"),
+});
+export type ApiLogSummary = z.infer<typeof apiLogSummarySchema>;

package/src/schemas/auth.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+export const storeRoleSchema = z.enum(["OWNER", "ADMIN", "STAFF"]);
+
+export type StoreRole = z.infer<typeof storeRoleSchema>;
+
+export const userTokenResponseSchema = z.object({
+  access_token: z.string(),
+  token_type: z.literal("Bearer"),
+  expires_in: z.number().int(),
+  refresh_token: z.string().optional(),
+});
+
+export type UserTokenResponse = z.infer<typeof userTokenResponseSchema>;
+
+/** client_credentials 응답 (RFC 6749 §4.4.3) — storeToken 직발급, refresh 없음 */
+export const clientCredentialsTokenResponseSchema = z.object({
+  access_token: z.string(),
+  token_type: z.literal("Bearer"),
+  expires_in: z.number().int(),
+  scope: z.string(),
+});
+export type ClientCredentialsTokenResponse = z.infer<typeof clientCredentialsTokenResponseSchema>;
+
+export const storeTokenResponseSchema = z.object({
+  access_token: z.string(),
+  token_type: z.literal("Bearer"),
+  expires_in: z.number().int(),
+  storeId: z.string(),
+  role: storeRoleSchema,
+  scopes: z.array(z.string()),
+});
+
+export type StoreTokenResponse = z.infer<typeof storeTokenResponseSchema>;
+
+export const myStoreSchema = z.object({
+  storeId: z.string(),
+  storeName: z.string(),
+  storeCode: z.string(),
+  role: storeRoleSchema,
+  status: z.enum(["ACTIVE", "SUSPENDED", "CLOSED"]),
+});
+
+export type MyStore = z.infer<typeof myStoreSchema>;
+
+export const myAccountSchema = z.object({
+  userId: z.string(),
+  email: z.email(),
+  name: z.string(),
+  storeCount: z.number().int(),
+  createdAt: z.string(),
+});
+
+export type MyAccount = z.infer<typeof myAccountSchema>;
+
+/** API 토큰(PAT) — 목록/조회 뷰 (평문·해시 미포함) */
+export const apiTokenSchema = z.object({
+  tokenId: z.string(),
+  name: z.string(),
+  prefix: z.string(),
+  scopes: z.array(z.string()),
+  createdBy: z.string().describe("발급자 userId"),
+  createdByName: z.string().nullable().describe("발급자 이름 (표시용). 계정이 없으면 null"),
+  createdByEmail: z.string().nullable().describe("발급자 이메일 (표시용). 계정이 없으면 null"),
+  createdAt: z.string(),
+  expiresAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+});
+export type ApiToken = z.infer<typeof apiTokenSchema>;
+
+/** 생성 응답 — 평문 토큰은 이 응답에서 단 한 번만 노출된다 */
+export const apiTokenCreatedSchema = apiTokenSchema.extend({ token: z.string() });
+export type ApiTokenCreated = z.infer<typeof apiTokenCreatedSchema>;
+
+export 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(),
+});
+export type ApiTokenCreateRequest = z.infer<typeof apiTokenCreateRequestSchema>;