@sayren/store-sdk 0.23.0 → 0.28.1

package/src/member-delegation.ts

@@ -1,9 +1,8 @@
 /**
- * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다
- * (token-exchange의 `member-uid`·`member-ref` 확장, auth-spec §12-10). 클라이언트 시크릿을 쓰므로 **서버에서만** 부른다.
+ * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다.
+ * 계정 토큰(개인 액세스 토큰 등)을 쓰므로 **서버에서만** 부른다.
  *
- * 스토어에 바인딩된 confidential 클라이언트 + `member:delegate` 스코프가 필요하다. 응답은 구매자 액세스 토큰(30분)이고
- * refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
+ * 응답은 구매자 액세스 토큰(30분)이고 refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
  */
 
 export interface DelegatedMemberToken {
@@ -12,87 +11,62 @@ export interface DelegatedMemberToken {
   memberId: string;
 }
 
-interface DelegationOptions {
-  /** api 주소(예: `https://api.sayren.app`) — `/v1/oauth2/token`을 붙인다 */
-  baseUrl: string;
-  clientId: string;
-  clientSecret: string;
-  fetch?: typeof globalThis.fetch;
-}
-
-/** 셀러 자체 인증의 사용자 id로 지목한다. 처음 보는 id면 구매자를 만든다(이메일·이름은 그때만 쓴다) */
-export function delegateMemberByUid(
-  options: DelegationOptions & {
-    uid: string;
-    email?: string;
-    name?: string;
-    /**
-     * 사용자가 내 서비스에서 실제로 로그인한 시각. 주면 구매자 토큰의 인증 시각이 되고(탈퇴처럼 최근 인증이 필요한 동작에
-     * 쓴다), 주지 않으면 인증 시각이 없는 토큰이 나온다
-     */
-    authenticatedAt?: Date;
-  },
-): Promise<DelegatedMemberToken> {
-  return delegate(options, {
-    subject_token_type: "urn:sayren:params:oauth:token-type:member-uid",
-    subject_token: options.uid,
-    ...(options.authenticatedAt
-      ? { subject_auth_time: String(Math.floor(options.authenticatedAt.getTime() / 1000)) }
-      : {}),
-    ...(options.email ? { subject_email: options.email } : {}),
-    ...(options.name ? { subject_name: options.name } : {}),
-  });
-}
-
-/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
-export function delegateMemberByEmail(
-  options: DelegationOptions & { email: string; name?: string },
-): Promise<DelegatedMemberToken> {
-  return delegate(options, {
-    subject_token_type: "urn:sayren:params:oauth:token-type:member-ref",
-    subject_token: options.email,
-    ...(options.name ? { subject_name: options.name } : {}),
-  });
+/** 위임 실패 — `error`는 api 오류 코드(엔벨로프 `error.code`, 없으면 `http_{status}`) */
+export class MemberDelegationError extends Error {
+  constructor(
+    readonly error: string,
+    readonly description: string,
+    readonly status: number,
+  ) {
+    super(description ? `${error}: ${description}` : error);
+    this.name = "MemberDelegationError";
+  }
 }
 
-async function delegate(
-  options: DelegationOptions,
-  subject: Record<string, string>,
-): Promise<DelegatedMemberToken> {
+/**
+ * 계정 토큰으로 구매자 위임(`POST /v1/customers/delegations`) — 계정 토큰(개인 액세스 토큰 등)과 상점 id를 쓴다.
+ * `customer:rw`가 필요하다. `uid`(셀러 자체 인증의 사용자 id) 또는 `email`로 지목하고, 처음 보는 사용자면 구매자를 만든다.
+ */
+export async function delegateMember(options: {
+  /** api 주소(예: `https://api.sayren.app`) */
+  baseUrl: string;
+  accessToken: string;
+  storeId: string;
+  uid?: string;
+  email?: string;
+  name?: string;
+  authenticatedAt?: Date;
+  fetch?: typeof globalThis.fetch;
+}): Promise<DelegatedMemberToken> {
   const doFetch = options.fetch ?? globalThis.fetch;
-  const basic = btoa(`${options.clientId}:${options.clientSecret}`);
-  const res = await doFetch(`${options.baseUrl.replace(/\/+$/, "")}/v1/oauth2/token`, {
+  const res = await doFetch(`${options.baseUrl.replace(/\/+$/, "")}/v1/customers/delegations`, {
     method: "POST",
     headers: {
-      "content-type": "application/x-www-form-urlencoded",
-      authorization: `Basic ${basic}`,
+      "content-type": "application/json",
+      authorization: `Bearer ${options.accessToken}`,
+      "x-store-id": options.storeId,
     },
-    body: new URLSearchParams({
-      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
-      ...subject,
-    }).toString(),
+    body: JSON.stringify({
+      ...(options.uid ? { uid: options.uid } : {}),
+      ...(options.email ? { email: options.email } : {}),
+      ...(options.name ? { name: options.name } : {}),
+      ...(options.authenticatedAt
+        ? { authenticatedAt: options.authenticatedAt.toISOString() }
+        : {}),
+    }),
   });
-  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
-  if (!res.ok || typeof body.access_token !== "string") {
-    const error = typeof body.error === "string" ? body.error : `http_${res.status}`;
-    const description = typeof body.error_description === "string" ? body.error_description : "";
-    throw new MemberDelegationError(error, description, res.status);
+  const body = (await res.json().catch(() => ({}))) as {
+    data?: { accessToken?: unknown; expiresIn?: unknown; memberId?: unknown };
+    error?: { code?: unknown; message?: unknown };
+  };
+  if (!res.ok || typeof body.data?.accessToken !== "string") {
+    const code = typeof body.error?.code === "string" ? body.error.code : `http_${res.status}`;
+    const message = typeof body.error?.message === "string" ? body.error.message : "";
+    throw new MemberDelegationError(code, message, res.status);
   }
   return {
-    accessToken: body.access_token,
-    expiresIn: Number(body.expires_in),
-    memberId: String(body.memberId),
+    accessToken: body.data.accessToken,
+    expiresIn: Number(body.data.expiresIn),
+    memberId: String(body.data.memberId),
   };
 }
-
-/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
-export class MemberDelegationError extends Error {
-  constructor(
-    readonly error: string,
-    readonly description: string,
-    readonly status: number,
-  ) {
-    super(description ? `${error}: ${description}` : error);
-    this.name = "MemberDelegationError";
-  }
-}

package/src/oauth.ts

@@ -4,10 +4,11 @@ import { unwrapData } from "./http";
 
 /**
  * OAuth 2.1 브라우저 플로우 헬퍼 (authorization_code + PKCE).
+ * 발급자는 Sayren 계정(accounts)이다 — 엔드포인트 주소는 호출부가 준다.
  * Web Crypto만 사용 — 브라우저/Node 모두에서 동작하며 **시크릿을 다루지 않는다**.
  */
 
-/** RFC 6749 §5.1 토큰 응답 (+ RFC 8693 확장 멤버 허용) */
+/** RFC 6749 §5.1 토큰 응답 */
 export const oauthTokenResponseSchema = z
   .object({
     access_token: z.string(),
@@ -29,19 +30,23 @@ export async function createPkcePair(): Promise<{ verifier: string; challenge: s
 }
 
 export interface AuthorizeUrlOptions {
-  /** 예: https://api.sayren.app/v1 (베이스 URL — /oauth2/authorize가 덧붙는다) */
-  baseUrl: string;
+  /** authorize 엔드포인트 전체 주소(예: `https://accounts.sayren.app/api/auth/oauth2/authorize`) */
+  authorizeUrl: string;
   clientId: string;
   redirectUri: string;
   state: string;
   codeChallenge: string;
-  /** 생략 시 서버 기본(stores:read). refresh가 필요하면 offline_access 포함 */
+  /** 생략 시 발급자 기본. refresh가 필요하면 offline_access 포함 */
   scope?: string;
+  /** RFC 8707 리소스 지시자 — 주면 JWT access token(`aud` = 리소스)을 받는다 */
+  resource?: string;
+  /** OIDC `prompt` — `login`(재인증)·`create`(가입)·`consent`(동의 다시 받기) */
+  prompt?: "login" | "create" | "consent";
 }
 
 /** authorize 엔드포인트 URL 구성 — 브라우저는 이 URL로 이동(top-level navigation) */
 export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
-  const url = new URL(`${options.baseUrl}/oauth2/authorize`);
+  const url = new URL(options.authorizeUrl);
   url.searchParams.set("response_type", "code");
   url.searchParams.set("client_id", options.clientId);
   url.searchParams.set("redirect_uri", options.redirectUri);
@@ -49,15 +54,18 @@ export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
   url.searchParams.set("code_challenge", options.codeChallenge);
   url.searchParams.set("code_challenge_method", "S256");
   if (options.scope) url.searchParams.set("scope", options.scope);
+  if (options.resource) url.searchParams.set("resource", options.resource);
+  if (options.prompt) url.searchParams.set("prompt", options.prompt);
   return url.toString();
 }
 
 async function tokenRequest(
-  baseUrl: string,
+  endpoint: string,
   form: Record<string, string>,
   fetchFn: typeof globalThis.fetch = globalThis.fetch,
 ): Promise<OAuthTokenResponse> {
-  const response = await fetchFn(`${baseUrl}/oauth2/token`, {
+  // 자격 증명(쿠키)을 싣지 않는다 — public 클라이언트 + PKCE·refresh로만 인증한다(다른 origin 발급자도 같다)
+  const response = await fetchFn(endpoint, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams(form).toString(),
@@ -70,23 +78,27 @@ async function tokenRequest(
   return oauthTokenResponseSchema.parse(unwrapData(json));
 }
 
-/** 콜백에서 받은 code를 userToken으로 교환 (PKCE verifier 동반) */
+/** 콜백에서 받은 code를 액세스 토큰으로 교환 (PKCE verifier 동반) */
 export async function exchangeAuthorizationCode(options: {
-  baseUrl: string;
+  /** 토큰 엔드포인트 전체 주소 */
+  tokenUrl: string;
   clientId: string;
   redirectUri: string;
   code: string;
   codeVerifier: string;
+  /** RFC 8707 리소스 지시자 */
+  resource?: string;
   fetch?: typeof globalThis.fetch;
 }): Promise<OAuthTokenResponse> {
   return tokenRequest(
-    options.baseUrl,
+    options.tokenUrl,
     {
       grant_type: "authorization_code",
       code: options.code,
       redirect_uri: options.redirectUri,
       client_id: options.clientId,
       code_verifier: options.codeVerifier,
+      ...(options.resource ? { resource: options.resource } : {}),
     },
     options.fetch,
   );
@@ -94,38 +106,21 @@ export async function exchangeAuthorizationCode(options: {
 
 /** refresh grant (rotation — 응답의 새 refresh_token으로 반드시 교체 저장할 것) */
 export async function refreshUserToken(options: {
-  baseUrl: string;
+  /** 토큰 엔드포인트 전체 주소 */
+  tokenUrl: string;
   clientId: string;
   refreshToken: string;
+  /** RFC 8707 리소스 지시자 */
+  resource?: string;
   fetch?: typeof globalThis.fetch;
 }): Promise<OAuthTokenResponse> {
   return tokenRequest(
-    options.baseUrl,
+    options.tokenUrl,
     {
       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.resource ? { resource: options.resource } : {}),
     },
     options.fetch,
   );

package/src/schemas/api-log.ts

@@ -1,14 +1,16 @@
 import { z } from "zod";
 
 /**
- * API 로그 — `/v1/api-logs`. 스토어가 해석된 관리 API(`/v1/**`) 요청을 7일간 보관한다.
- * 인증에 실패해 스토어를 알 수 없는 요청(401 등)은 기록되지 않는다.
+ * API 로그 — `/v1/api-logs`. 상점이 해석된 관리 API(`/v1/**`) 요청을 7일간 보관한다.
+ * 인증에 실패해 상점을 알 수 없는 요청(401 등)은 기록되지 않는다.
  * Authorization·쿠키 헤더, 요청 본문, 개인정보는 저장하지 않는다.
  */
 
 export const apiLogPrincipalTypeSchema = z
   .enum(["USER", "PAT", "CLIENT"])
-  .describe("호출 주체 유형. `USER`=콘솔 사용자, `PAT`=API 토큰, `CLIENT`=앱(OAuth 클라이언트)");
+  .describe(
+    "호출 주체 유형. `USER`=상점 플랫폼 사용자, `PAT`=API 토큰, `CLIENT`=앱(OAuth 클라이언트)",
+  );
 export type ApiLogPrincipalType = z.infer<typeof apiLogPrincipalTypeSchema>;
 
 export const apiLogPrincipalSchema = z.object({
@@ -100,7 +102,7 @@ export type ApiLogPage = z.infer<typeof apiLogPageSchema>;
 
 /**
  * API 로그 요약 — `GET /api-logs/summary`. 연동 트래픽(호출 주체 `PAT`·`CLIENT`)만 집계하며
- * 콘솔 사용자(`USER`) 요청은 제외한다
+ * 상점 플랫폼 사용자(`USER`) 요청은 제외한다
  */
 export const apiLogSummarySchema = z.object({
   windowHours: z.number().int().describe("집계 구간(시간). 최근 24시간"),
@@ -108,7 +110,7 @@ export const apiLogSummarySchema = z.object({
     .number()
     .int()
     .min(0)
-    .describe("구간 내 연동 요청 수 (호출 주체 `PAT`·`CLIENT`, 콘솔 사용자 제외)"),
+    .describe("구간 내 연동 요청 수 (호출 주체 `PAT`·`CLIENT`, 상점 플랫폼 사용자 제외)"),
   errors: z.number().int().min(0).describe("구간 내 연동 요청 중 4xx·5xx 응답 수"),
   serverErrors: z.number().int().min(0).describe("구간 내 연동 요청 중 5xx 응답 수"),
 });

package/src/schemas/audit.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 export const auditActorTypeSchema = z
   .enum(["USER", "AGENT", "APP", "TOKEN", "SYSTEM"])
   .describe(
-    "행위자 유형. `USER`=콘솔 사용자, `AGENT`=AI 에이전트(MCP·에이전트용 API 토큰), `APP`=앱(OAuth 클라이언트·M2M), " +
+    "행위자 유형. `USER`=상점 플랫폼 사용자, `AGENT`=AI 에이전트(MCP·에이전트용 API 토큰), `APP`=앱(OAuth 클라이언트·M2M), " +
       "`TOKEN`=API 토큰, `SYSTEM`=자동화(주기 잡)",
   );
 export type AuditActorType = z.infer<typeof auditActorTypeSchema>;
@@ -55,7 +55,7 @@ export const auditLogSchema = z.object({
   actorRole: z
     .string()
     .nullable()
-    .describe("요청 시점의 스토어 역할. 역할이 없는 토큰·자동화는 null"),
+    .describe("요청 시점의 상점 역할. 역할이 없는 토큰·자동화는 null"),
   target: z.object({
     type: z.string().describe("대상 리소스 유형 (예: `products`, `order-items`, `claim`)"),
     id: z
@@ -144,7 +144,7 @@ export type AuditLogPage = z.infer<typeof auditLogPageSchema>;
 export const agentPolicyDecisionSchema = z
   .enum(["ALLOW", "APPROVAL_REQUIRED", "DENIED"])
   .describe(
-    "에이전트 쓰기 판정. `ALLOW`=바로 실행, `APPROVAL_REQUIRED`=콘솔 승인 뒤 실행, `DENIED`=에이전트는 실행할 수 없음",
+    "에이전트 쓰기 판정. `ALLOW`=바로 실행, `APPROVAL_REQUIRED`=상점 플랫폼 승인 뒤 실행, `DENIED`=에이전트는 실행할 수 없음",
   );
 export type AgentPolicyDecision = z.infer<typeof agentPolicyDecisionSchema>;
 
@@ -208,7 +208,7 @@ export const approvalRequestSchema = z.object({
   decidedBy: z
     .object({ id: z.string(), name: z.string().nullable() })
     .nullable()
-    .describe("승인·거절한 콘솔 사용자"),
+    .describe("승인·거절한 상점 플랫폼 사용자"),
   decisionNote: z.string().nullable().describe("승인·거절 메모"),
   executedAt: z.string().nullable().describe("원 요청 실행을 마친 일시"),
   result: z
@@ -227,7 +227,7 @@ export const approvalRequestSchema = z.object({
   approvalUrl: z
     .string()
     .nullable()
-    .describe("셀러 콘솔의 승인 화면 주소. 이 배포의 콘솔 주소를 알 수 없으면 null"),
+    .describe("상점 플랫폼의 승인 화면 주소. 이 배포의 상점 플랫폼 주소를 알 수 없으면 null"),
 });
 export type ApprovalRequest = z.infer<typeof approvalRequestSchema>;
 

package/src/schemas/auth.ts

@@ -4,35 +4,6 @@ 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(),
@@ -52,38 +23,3 @@ export const myAccountSchema = z.object({
 });
 
 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(),
-  agent: z
-    .boolean()
-    .default(false)
-    .describe(
-      "AI 에이전트(MCP)용 토큰인가. true면 이 토큰의 쓰기는 행위자 `AGENT`로 기록되고 에이전트 쓰기 정책(승인 필요·거부)을 따른다",
-    ),
-});
-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(),
-  /** AI 에이전트(MCP)용 토큰. 생략 = false. 발급 뒤에는 바꿀 수 없다 */
-  agent: z.boolean().optional(),
-});
-export type ApiTokenCreateRequest = z.infer<typeof apiTokenCreateRequestSchema>;

package/src/schemas/claim.ts

@@ -31,10 +31,10 @@ export const claimReasonSchema = z.enum([
 export type ClaimReason = z.infer<typeof claimReasonSchema>;
 
 /**
- * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 상점 주소록의 기본 반품지이거나,
  * 상품이 반품지를 따로 지정했으면 그 주소다.
  *
- * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 상점도 null이다.
  * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
  */
 export const claimReturnAddressSchema = z.object({
@@ -102,8 +102,8 @@ export const claimSchema = z.object({
   returnAddress: claimReturnAddressSchema
     .nullable()
     .describe(
-      "수거 안내에 쓸 반품지(이슈 #30). 상품이 지정한 반품지, 없으면 스토어 기본 반품지다. " +
-        "취소 클레임과 반품지를 등록하지 않은 스토어는 null",
+      "수거 안내에 쓸 반품지(이슈 #30). 상품이 지정한 반품지, 없으면 상점 기본 반품지다. " +
+        "취소 클레임과 반품지를 등록하지 않은 상점은 null",
     ),
 });
 

package/src/schemas/coupon.ts

@@ -45,7 +45,7 @@ const limitField = (description: string) =>
 const descriptions = {
   name: "구매자에게 보이는 쿠폰 이름. 1~60자",
   description: "구매자에게 보이는 설명. 300자까지",
-  code: "쿠폰 코드 — 발급 방식이 `CODE`일 때 필수. 영문·숫자·`-`·`_` 6~30자, 대소문자 구분 없음(대문자로 저장). 스토어 안에서 유일하다",
+  code: "쿠폰 코드 — 발급 방식이 `CODE`일 때 필수. 영문·숫자·`-`·`_` 6~30자, 대소문자 구분 없음(대문자로 저장). 상점 안에서 유일하다",
   startsAt: "사용 시작 시각(ISO 8601, 시간대 포함). 생략하면 바로 쓸 수 있다",
   endsAt:
     "사용 종료 시각(ISO 8601, 시간대 포함). 이 시각부터 못 쓴다. 생략하면 제한이 없다. " +
@@ -247,7 +247,7 @@ export const issueCouponResultSchema = z.object({
       code: z
         .string()
         .describe(
-          "실패 사유. `CUSTOMER_NOT_FOUND`(이 스토어 구매자가 아님)·`COUPON_LIMIT_REACHED`(1인 발급 한도)·" +
+          "실패 사유. `CUSTOMER_NOT_FOUND`(이 상점 구매자가 아님)·`COUPON_LIMIT_REACHED`(1인 발급 한도)·" +
             "`COUPON_EXHAUSTED`(총 발급 한도)",
         ),
       message: z.string(),

package/src/schemas/customer-delegation.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+/**
+ * 구매자 위임 REST(`POST /v1/customers/delegations`, #71) — 계정 토큰(또는 관리 API 토큰) + `X-Store-Id`로 부른다(`customer:rw`).
+ * 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰(30분, refresh 없음)으로 바꾼다. 옛 token-exchange
+ * (`member-uid`·`member-ref`)를 대신한다. 에이전트 요청은 거부된다(`x-agent-policy` DENIED).
+ */
+
+const uidPattern = /^[A-Za-z0-9._:@|-]{1,128}$/;
+
+export const customerDelegationRequestSchema = z
+  .object({
+    uid: z
+      .string()
+      .regex(uidPattern)
+      .optional()
+      .describe(
+        "셀러 자체 인증의 사용자 id(1~128자, 영문·숫자·`._:@|-`). 처음 보는 id면 구매자를 만든다",
+      ),
+    email: z
+      .email()
+      .max(254)
+      .optional()
+      .describe("uid가 없으면 이메일로 지목한다. uid와 함께 주면 처음 만들 때의 이메일이다"),
+    name: z.string().max(50).optional().describe("처음 만들 때의 이름"),
+    authenticatedAt: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe(
+        "사용자가 셀러 서비스에서 실제로 로그인한 시각(uid 위임만). 주면 구매자 토큰의 인증 시각이 된다",
+      ),
+  })
+  .refine((value) => Boolean(value.uid || value.email), {
+    message: "uid 또는 email이 필요합니다",
+    path: ["uid"],
+  })
+  .describe("구매자 위임 요청");
+export type CustomerDelegationRequest = z.infer<typeof customerDelegationRequestSchema>;
+
+export const customerDelegationSchema = z
+  .object({
+    accessToken: z.string().describe("구매자 액세스 토큰(스토어프론트 API Bearer)"),
+    tokenType: z.literal("Bearer"),
+    expiresIn: z.number().int().describe("수명(초)"),
+    memberId: z.string(),
+  })
+  .describe("구매자 위임 결과");
+export type CustomerDelegation = z.infer<typeof customerDelegationSchema>;

package/src/schemas/customer.ts

@@ -88,7 +88,7 @@ export const customerConsentSchema = z.object({
   kind: consentKindSchema,
   /** 동의한 약관 버전. 마케팅은 버전이 없어 null */
   version: z.string().nullable(),
-  /** 동의 시점의 약관 문서 주소. 스토어가 주소를 정하지 않았거나 마케팅이면 null */
+  /** 동의 시점의 약관 문서 주소. 상점이 주소를 정하지 않았거나 마케팅이면 null */
   documentUrl: z.string().nullable(),
   action: consentActionSchema,
   source: consentSourceSchema,
@@ -102,9 +102,9 @@ export const customerConsentStateSchema = z.object({
   agreed: z.boolean(),
   /** 동의한 약관 버전. 마케팅이거나 이력이 없으면 null */
   agreedVersion: z.string().nullable(),
-  /** 스토어의 현재 약관 버전. 마케팅은 null */
+  /** 상점의 현재 약관 버전. 마케팅은 null */
   currentVersion: z.string().nullable(),
-  /** 스토어가 정한 현재 약관 문서 주소. 정하지 않았거나 마케팅이면 null */
+  /** 상점이 정한 현재 약관 문서 주소. 정하지 않았거나 마케팅이면 null */
   currentDocumentUrl: z.string().nullable(),
   updatedAt: z.string().nullable(),
   /** 약관이 개정돼 다시 받아야 하는가. 마케팅은 항상 false */

package/src/schemas/fulfillment.ts

@@ -107,11 +107,11 @@ const KNOWN_FULFILLMENT_TYPES: readonly string[] = fulfillmentTypeSchema.options
 
 const ADDRESS_ID_DESCRIPTIONS = {
   shipping:
-    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 등록에서 생략하면 그 시점 스토어 기본 출고지를 저장한다. " +
-    "`null`이면 비워 둔다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 등록에서 생략하면 그 시점 상점 기본 출고지를 저장한다. " +
+    "`null`이면 비워 둔다(상점 기본 출고지를 따른다). 이 상점의 `SHIPPING` 주소가 아니면 거부한다",
   return:
-    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 등록에서 생략하면 그 시점 스토어 기본 반품지를 저장한다. " +
-    "`null`이면 비워 둔다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다",
+    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 등록에서 생략하면 그 시점 상점 기본 반품지를 저장한다. " +
+    "`null`이면 비워 둔다(상점 기본 반품지를 따른다). 이 상점의 `RETURN` 주소가 아니면 거부한다",
 } as const;
 
 /**
@@ -161,7 +161,7 @@ const shippingCreateSchema = z
       .min(0)
       .optional()
       .describe(
-        "배송비. 원 단위. 생략하면 스토어 기본 배송비(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 저장한다. FREE면 0이거나 생략한다",
+        "배송비. 원 단위. 생략하면 상점 기본 배송비(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 저장한다. FREE면 0이거나 생략한다",
       ),
     conditionalFreeAmount: z
       .number()
@@ -176,7 +176,7 @@ const shippingCreateSchema = z
   .superRefine(refineShippingConsistency);
 
 /**
- * 상품 이행 — 등록(POST). 배송 상품의 `shipping`을 생략하면 기본값(유료 배송·스토어 기본 배송비·기본 출고지·반품지)이다.
+ * 상품 이행 — 등록(POST). 배송 상품의 `shipping`을 생략하면 기본값(유료 배송·상점 기본 배송비·기본 출고지·반품지)이다.
  */
 export const productFulfillmentCreateSchema = z.discriminatedUnion("type", [
   z.strictObject({ type: z.literal("SHIPPING"), shipping: shippingCreateSchema.optional() }),
@@ -235,11 +235,11 @@ export const productFulfillmentSchema = z.discriminatedUnion("type", [
       shippingAddressId: z
         .string()
         .nullable()
-        .describe("출고지 주소 id. null이면 스토어 기본 출고지를 따른다"),
+        .describe("출고지 주소 id. null이면 상점 기본 출고지를 따른다"),
       returnAddressId: z
         .string()
         .nullable()
-        .describe("반품지 주소 id. null이면 스토어 기본 반품지를 따른다"),
+        .describe("반품지 주소 id. null이면 상점 기본 반품지를 따른다"),
     }),
   }),
   z.object({ type: z.literal("MANUAL") }),
@@ -306,9 +306,7 @@ export const orderItemFulfillmentSnapshotSchema = z.discriminatedUnion("type", [
       returnAddressId: z
         .string()
         .nullable()
-        .describe(
-          "주문 시점 반품지 주소 id. null이거나 지워진 주소면 스토어 기본 반품지로 안내한다",
-        ),
+        .describe("주문 시점 반품지 주소 id. null이거나 지워진 주소면 상점 기본 반품지로 안내한다"),
     }),
   }),
   z.object({ type: z.literal("MANUAL") }),

package/src/schemas/order.ts

@@ -328,7 +328,7 @@ export const dispatchRequestSchema = z
      * 발송 시각. ISO 8601이고 시간대(`Z` 또는 `+09:00`)를 포함해야 한다. 생략하면 현재 시각이다.
      *
      * 전에는 `z.string()`이라 아무 문자열이나 그대로 저장됐다. 이 값은 배송 정보 jsonb에 들어가
-     * 자동 배송완료·추적 동기화 잡의 대상 선별 조건이 된다 — 잘못된 한 행이 스토어 구분 없이 도는
+     * 자동 배송완료·추적 동기화 잡의 대상 선별 조건이 된다 — 잘못된 한 행이 상점 구분 없이 도는
      * 잡 전체를 멈출 수 있어 입력에서 좁혔다. 검증을 통과한 값도 저장 전에 UTC ISO로 정규화한다.
      */
     dispatchedAt: z.iso.datetime({ offset: true }).optional(),