@sayren/store-sdk 0.23.0 → 0.28.1

package/dist/server.d.mts

@@ -1,47 +1,38 @@
 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";
 //#region src/member-delegation.d.ts
 /**
- * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다
- * (token-exchange의 `member-uid`·`member-ref` 확장, auth-spec §12-10). 클라이언트 시크릿을 쓰므로 **서버에서만** 부른다.
+ * 구매자 위임 — 자체 회원 시스템을 가진 셀러 서버가 로그인한 사용자를 sayren 구매자 토큰으로 바꾼다.
+ * 계정 토큰(개인 액세스 토큰 등)을 쓰므로 **서버에서만** 부른다.
  *
- * 스토어에 바인딩된 confidential 클라이언트 + `member:delegate` 스코프가 필요하다. 응답은 구매자 액세스 토큰(30분)이고
- * refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
+ * 응답은 구매자 액세스 토큰(30분)이고 refresh는 없다 — 만료되면 같은 호출로 다시 받는다.
  */
 interface DelegatedMemberToken {
   accessToken: string;
   expiresIn: number;
   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 declare function delegateMemberByUid(options: DelegationOptions & {
-  uid: string;
-  email?: string;
-  name?: string;
-  /**
-   * 사용자가 내 서비스에서 실제로 로그인한 시각. 주면 구매자 토큰의 인증 시각이 되고(탈퇴처럼 최근 인증이 필요한 동작에
-   * 쓴다), 주지 않으면 인증 시각이 없는 토큰이 나온다
-   */
-  authenticatedAt?: Date;
-}): Promise<DelegatedMemberToken>;
-/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
-export declare function delegateMemberByEmail(options: DelegationOptions & {
-  email: string;
-  name?: string;
-}): Promise<DelegatedMemberToken>;
-/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
+/** 위임 실패 — `error`는 api 오류 코드(엔벨로프 `error.code`, 없으면 `http_{status}`) */
 export declare class MemberDelegationError extends Error {
   readonly error: string;
   readonly description: string;
   readonly status: number;
   constructor(error: string, description: string, status: number);
 }
+/**
+ * 계정 토큰으로 구매자 위임(`POST /v1/customers/delegations`) — 계정 토큰(개인 액세스 토큰 등)과 상점 id를 쓴다.
+ * `customer:rw`가 필요하다. `uid`(셀러 자체 인증의 사용자 id) 또는 `email`로 지목하고, 처음 보는 사용자면 구매자를 만든다.
+ */
+export declare 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>;
 //#endregion
 //#region src/webhook-signature.d.ts
 interface SignWebhookPayloadOptions {

package/dist/server.mjs

@@ -1,46 +1,6 @@
 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-ap_exsb9.mjs";
 //#region src/member-delegation.ts
-/** 셀러 자체 인증의 사용자 id로 지목한다. 처음 보는 id면 구매자를 만든다(이메일·이름은 그때만 쓴다) */
-function delegateMemberByUid(options) {
-	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() / 1e3)) } : {},
-		...options.email ? { subject_email: options.email } : {},
-		...options.name ? { subject_name: options.name } : {}
-	});
-}
-/** 이메일로 지목한다. 처음 보는 이메일이면 구매자를 만든다 */
-function delegateMemberByEmail(options) {
-	return delegate(options, {
-		subject_token_type: "urn:sayren:params:oauth:token-type:member-ref",
-		subject_token: options.email,
-		...options.name ? { subject_name: options.name } : {}
-	});
-}
-async function delegate(options, subject) {
-	const doFetch = options.fetch ?? globalThis.fetch;
-	const basic = btoa(`${options.clientId}:${options.clientSecret}`);
-	const res = await doFetch(`${options.baseUrl.replace(/\/+$/, "")}/v1/oauth2/token`, {
-		method: "POST",
-		headers: {
-			"content-type": "application/x-www-form-urlencoded",
-			authorization: `Basic ${basic}`
-		},
-		body: new URLSearchParams({
-			grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
-			...subject
-		}).toString()
-	});
-	const body = await res.json().catch(() => ({}));
-	if (!res.ok || typeof body.access_token !== "string") throw new MemberDelegationError(typeof body.error === "string" ? body.error : `http_${res.status}`, typeof body.error_description === "string" ? body.error_description : "", res.status);
-	return {
-		accessToken: body.access_token,
-		expiresIn: Number(body.expires_in),
-		memberId: String(body.memberId)
-	};
-}
-/** 위임 실패 — `error`는 OAuth 오류 코드(`invalid_client`·`invalid_scope`·`invalid_request` 등) */
+/** 위임 실패 — `error`는 api 오류 코드(엔벨로프 `error.code`, 없으면 `http_{status}`) */
 var MemberDelegationError = class extends Error {
 	error;
 	description;
@@ -53,6 +13,33 @@ var MemberDelegationError = class extends Error {
 		this.name = "MemberDelegationError";
 	}
 };
+/**
+* 계정 토큰으로 구매자 위임(`POST /v1/customers/delegations`) — 계정 토큰(개인 액세스 토큰 등)과 상점 id를 쓴다.
+* `customer:rw`가 필요하다. `uid`(셀러 자체 인증의 사용자 id) 또는 `email`로 지목하고, 처음 보는 사용자면 구매자를 만든다.
+*/
+async function delegateMember(options) {
+	const res = await (options.fetch ?? globalThis.fetch)(`${options.baseUrl.replace(/\/+$/, "")}/v1/customers/delegations`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			authorization: `Bearer ${options.accessToken}`,
+			"x-store-id": options.storeId
+		},
+		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(() => ({}));
+	if (!res.ok || typeof body.data?.accessToken !== "string") throw new MemberDelegationError(typeof body.error?.code === "string" ? body.error.code : `http_${res.status}`, typeof body.error?.message === "string" ? body.error.message : "", res.status);
+	return {
+		accessToken: body.data.accessToken,
+		expiresIn: Number(body.data.expiresIn),
+		memberId: String(body.data.memberId)
+	};
+}
 //#endregion
 //#region src/webhook-signature.ts
 /**
@@ -177,4 +164,4 @@ async function verifyWebhookSignature(options) {
 	};
 }
 //#endregion
-export { MemberDelegationError, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, delegateMemberByEmail, delegateMemberByUid, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature };
+export { MemberDelegationError, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, delegateMember, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature };

package/package.json

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

package/src/client.ts

@@ -1,14 +1,5 @@
 import { z } from "zod";
-import { base64Utf8 } from "./base64";
-import {
-  ApiError,
-  createHttp,
-  path,
-  type Query,
-  resolveToken,
-  type TokenSource,
-  unwrapData,
-} from "./http";
+import { ApiError, createHttp, path, type Query, resolveToken, type TokenSource } from "./http";
 import {
   type AnalyticsPagesParams,
   type AnalyticsProductsParams,
@@ -29,14 +20,6 @@ import {
   analyticsSourcesQuerySchema,
   analyticsSourcesSchema,
 } from "./schemas/analytics";
-import {
-  type ApiClientListParams,
-  apiClientSchema,
-  apiClientSecretRotatedSchema,
-  type OAuthClientRegistrationRequest,
-  oauthClientRegistrationRequestSchema,
-  oauthClientRegistrationResponseSchema,
-} from "./schemas/api-client";
 import { type ApiLogListOptions, apiLogPageSchema, apiLogSummarySchema } from "./schemas/api-log";
 import {
   type ApprovalDecisionRequest,
@@ -47,15 +30,7 @@ import {
   approvalRequestSchema,
   auditLogPageSchema,
 } from "./schemas/audit";
-import {
-  type ApiTokenCreateRequest,
-  apiTokenCreatedSchema,
-  apiTokenCreateRequestSchema,
-  apiTokenSchema,
-  clientCredentialsTokenResponseSchema,
-  myAccountSchema,
-  myStoreSchema,
-} from "./schemas/auth";
+import { myAccountSchema, myStoreSchema } from "./schemas/auth";
 import {
   type CategoryCreateRequest,
   type CategoryDeleteStrategy,
@@ -292,6 +267,7 @@ import {
   type WriteStorefrontFilesRequest,
   writeStorefrontFilesRequestSchema,
 } from "./schemas/storefront-hosting";
+import { publicPlansSchema, storeSubscriptionSchema } from "./schemas/subscription";
 import {
   type UploadPurpose,
   type UploadRequest,
@@ -305,20 +281,16 @@ import type { AuthorizeOptions, StoreSession } from "./session";
 export interface StoreClientOptions {
   /** 예: https://api.example.com/v1 */
   baseUrl: string;
-  /** 유저 토큰 (1단계). 인증/스토어 목록 API에 사용 */
-  userToken?: TokenSource;
-  /** 스토어 토큰 (3단계). 테넌트 리소스 API에 사용 */
-  storeToken?: TokenSource;
-  /** 테넌트 storeId — storeHttp(테넌트 리소스) 요청에 X-Store-Id로 실린다(userToken 직접 인가). */
-  storeId?: TokenSource;
   /**
-   * 토큰 주입 모드 — PAT/storeToken급(테넌트 바인딩, role 없음)을 storeHttp Bearer로 싣는다.
-   * userToken이 아니다(비인터랙티브 M2M/CLI 경로용). storeToken과 함께 주면 storeToken이 우선한다.
+   * 계정 토큰(accounts가 발급한 JWT — 상점 플랫폼 로그인, 개인 액세스 토큰, 연결된 앱의 토큰).
+   * 계정 API(`/me/*`)와 상점 API 모두에 Bearer로 싣는다. `session`을 주면 생략해도 세션 토큰을 쓴다.
    */
-  auth?: { apiToken?: string };
+  accessToken?: TokenSource;
+  /** 대상 상점 id — 상점 API 요청에 `X-Store-Id`로 싣는다. 계정 API(`/me/*`)에는 싣지 않는다 */
+  storeId?: TokenSource;
   /**
-   * SDK 세션 매니저 — 전달하면 userToken(Bearer)·401 refresh·복구불가 시 clear를
-   * 이 세션에서 자동 배선한다. 개별 옵션(userToken/refresh/onUnauthorized)을 명시하면 그쪽이 우선한다.
+   * SDK 세션 매니저 — 전달하면 Bearer 토큰·401 refresh·복구 불가 시 clear를
+   * 이 세션에서 자동 배선한다. 개별 옵션(accessToken/refresh/onUnauthorized)을 명시하면 그쪽이 우선한다.
    */
   session?: StoreSession;
   /** 401 시 세션 갱신 시도 — true면 요청을 1회 재시도한다(refresh 토큰 회전) */
@@ -328,44 +300,37 @@ export interface StoreClientOptions {
   fetch?: typeof globalThis.fetch;
 }
 
-function formBody(fields: Record<string, string>): string {
-  return new URLSearchParams(fields).toString();
-}
-
 export function createStoreClient(options: StoreClientOptions) {
   const fetchFn = options.fetch ?? globalThis.fetch;
   const { session } = options;
 
-  // session이 있으면 userToken/refresh/onUnauthorized의 기본값을 세션에서 배선한다.
-  // 개별 옵션을 명시하면 그쪽이 우선(하위호환) — session 미전달 시 기존 동작 그대로.
-  const userTokenSource: TokenSource =
-    options.userToken ?? (session ? () => session.getToken() : undefined);
+  // session이 있으면 토큰/refresh/onUnauthorized의 기본값을 세션에서 배선한다. 개별 옵션을 명시하면 그쪽이 우선한다.
+  const tokenSource: TokenSource =
+    options.accessToken ?? (session ? () => session.getToken() : undefined);
   const refresh = options.refresh ?? (session ? () => session.refresh() : undefined);
   const onUnauthorized = options.onUnauthorized ?? (session ? () => session.clear() : undefined);
-  // storeToken(명시 옵션)이 auth.apiToken(PAT/storeToken급 주입)보다 우선한다.
-  const storeTokenSource: TokenSource = options.storeToken ?? options.auth?.apiToken;
 
+  function bearer(): Record<string, string> {
+    const token = resolveToken(tokenSource);
+    return token ? { authorization: `Bearer ${token}` } : {};
+  }
+
+  /** 계정 API(`/me/*`) — 상점을 고르지 않는다 */
   const userHttp = createHttp({
     baseUrl: options.baseUrl,
     fetch: fetchFn,
-    headers: () => {
-      const token = resolveToken(userTokenSource);
-      return token ? { authorization: `Bearer ${token}` } : ({} as Record<string, string>);
-    },
+    headers: bearer,
     refresh,
     onUnauthorized,
   });
 
+  /** 상점 API — 같은 계정 토큰 + `X-Store-Id` */
   const storeHttp = createHttp({
     baseUrl: options.baseUrl,
     fetch: fetchFn,
     headers: () => {
-      const token = resolveToken(storeTokenSource);
       const storeId = resolveToken(options.storeId);
-      return {
-        ...(token ? { authorization: `Bearer ${token}` } : {}),
-        ...(storeId ? { "x-store-id": storeId } : {}),
-      };
+      return { ...bearer(), ...(storeId ? { "x-store-id": storeId } : {}) };
     },
     refresh,
     onUnauthorized,
@@ -391,7 +356,7 @@ export function createStoreClient(options: StoreClientOptions) {
   }
 
   return {
-    /** session의 현재 userToken (session 미배선 시 null — 던지지 않음) */
+    /** session의 현재 액세스 토큰 (session 미배선 시 null — 던지지 않음) */
     get accessToken(): string | null {
       return session ? session.accessToken : null;
     },
@@ -405,90 +370,11 @@ export function createStoreClient(options: StoreClientOptions) {
     userinfo: () => requireSession().userinfo(),
 
     auth: {
-      /**
-       * 서버 간 연동(M2M) — client_credentials grant (client_secret_basic).
-       * 클라이언트가 스토어에 바인딩되어 있어 **storeToken이 곧바로 발급**된다.
-       * ⚠ client_secret은 서버 환경에서만 사용할 것 (브라우저 반입 금지)
-       */
-      async issueStoreTokenByClientCredentials(
-        clientId: string,
-        clientSecret: string,
-        scope?: string,
-      ) {
-        // RFC 7617 client_secret_basic — UTF-8 바이트를 base64로 인코딩한다.
-        const credentials = base64Utf8(`${clientId}:${clientSecret}`);
-        const response = await fetchFn(`${options.baseUrl}/oauth2/token`, {
-          method: "POST",
-          headers: {
-            "content-type": "application/x-www-form-urlencoded",
-            authorization: `Basic ${credentials}`,
-          },
-          body: formBody({ grant_type: "client_credentials", ...(scope ? { scope } : {}) }),
-        });
-        if (!response.ok) {
-          const body = (await response.json().catch(() => null)) as {
-            error_description?: string;
-          } | null;
-          throw new Error(body?.error_description ?? `토큰 발급 실패 (HTTP ${response.status})`);
-        }
-        return clientCredentialsTokenResponseSchema.parse(unwrapData(await response.json()));
-      },
-      /** 2단계 — 소속 스토어 목록 */
+      /** 소속 상점 목록 */
       listMyStores: () => userHttp.request("GET", "/me/stores", z.array(myStoreSchema)),
-      /** RFC 7009 — token을 폐기한다 (public client는 client_id만 동반) */
-      async revoke(token: string, clientId: string) {
-        await fetchFn(`${options.baseUrl}/oauth2/revoke`, {
-          method: "POST",
-          headers: { "content-type": "application/x-www-form-urlencoded" },
-          body: formBody({ token, client_id: clientId }),
-        });
-      },
       me: () => userHttp.request("GET", "/me", myAccountSchema),
     },
 
-    /** API 토큰(PAT) 관리 — OWNER/ADMIN 전용. 발급된 토큰은 storeToken처럼 Bearer로 사용 */
-    apiTokens: {
-      create: (body: ApiTokenCreateRequest) =>
-        storeHttp.request("POST", "/store/api-tokens", apiTokenCreatedSchema, {
-          body: apiTokenCreateRequestSchema.parse(body),
-        }),
-      list: () => storeHttp.request("GET", "/store/api-tokens", z.array(apiTokenSchema)),
-      revoke: (tokenId: string) =>
-        storeHttp.requestVoid("DELETE", path`/store/api-tokens/${tokenId}`),
-    },
-
-    /**
-     * 앱(OAuth 클라이언트) 관리 — OWNER/ADMIN storeToken 전용(PAT·M2M 거부). auth-spec §12, 부록 B-13.
-     * 시크릿 평문은 register·rotateSecret 응답에서만 한 번 노출된다(apiTokens.create와 같은 성격).
-     */
-    apiClients: {
-      /**
-       * DCR 등록 (RFC 7591) — `POST /v1/oauth2/register`. OAuth 프로토콜 표면이라 응답이 평면 JSON이다.
-       * 등록 오류(`invalid_client_metadata`·`invalid_redirect_uri`)는 ApiError(code=error,
-       * message=error_description)로, Bearer 인증 오류는 엔벨로프 그대로 ApiError로 던진다.
-       */
-      register: (body: OAuthClientRegistrationRequest) =>
-        storeHttp.request("POST", "/oauth2/register", oauthClientRegistrationResponseSchema, {
-          body: oauthClientRegistrationRequestSchema.parse(body),
-        }),
-      list: (params?: ApiClientListParams) =>
-        storeHttp.request("GET", "/store/api-clients", z.array(apiClientSchema), {
-          query: params as Query,
-        }),
-      get: (clientId: string) =>
-        storeHttp.request("GET", path`/store/api-clients/${clientId}`, apiClientSchema),
-      /** confidential 전용. 기존 시크릿은 즉시 무효(유예 없음) */
-      rotateSecret: (clientId: string) =>
-        storeHttp.request(
-          "POST",
-          path`/store/api-clients/${clientId}/rotate-secret`,
-          apiClientSecretRotatedSchema,
-        ),
-      /** REVOKED로 전환(되돌릴 수 없음). 이미 비활성이면 현재 상태를 그대로 돌려준다 */
-      deactivate: (clientId: string) =>
-        storeHttp.request("POST", path`/store/api-clients/${clientId}/deactivate`, apiClientSchema),
-    },
-
     /**
      * 미디어 업로드 — 자리를 받아(`POST /uploads`) 파일 바이트는 호출자가
      * `uploadUrl`로 직접 PUT한다. 업로드가 끝나면 `url`이 공개 주소가 된다.
@@ -605,7 +491,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       get: (optionSetId: string) =>
         storeHttp.request("GET", path`/saved-option-sets/${optionSetId}`, savedOptionSetSchema),
-      /** 이름이 겹치면 409 `OPTION_SET_NAME_TAKEN`, 스토어당 200개를 넘으면 409 `OPTION_SET_LIMIT_EXCEEDED` */
+      /** 이름이 겹치면 409 `OPTION_SET_NAME_TAKEN`, 상점당 200개를 넘으면 409 `OPTION_SET_LIMIT_EXCEEDED` */
       create: (body: SavedOptionSetRequestInput) =>
         storeHttp.request("POST", "/saved-option-sets", savedOptionSetSchema, {
           body: savedOptionSetRequestSchema.parse(body),
@@ -675,7 +561,7 @@ export function createStoreClient(options: StoreClientOptions) {
       get: (orderId: string) => storeHttp.request("GET", path`/orders/${orderId}`, orderSchema),
       /**
        * `POST /v1/orders/{orderId}/cash-receipt/reissue` — 실패했거나 재시도 대기 중인 현금영수증을 지금 다시 발급·취소한다.
-       * 콘솔 OWNER·ADMIN 전용(PAT·M2M 403 `INSUFFICIENT_ROLE`). 404 `CASH_RECEIPT_NOT_FOUND`, 409 `CASH_RECEIPT_NOT_REISSUABLE`
+       * 상점 플랫폼 OWNER·ADMIN 전용(PAT·M2M 403 `INSUFFICIENT_ROLE`). 404 `CASH_RECEIPT_NOT_FOUND`, 409 `CASH_RECEIPT_NOT_REISSUABLE`
        */
       reissueCashReceipt: (orderId: string) =>
         storeHttp.request("POST", path`/orders/${orderId}/cash-receipt/reissue`, cashReceiptSchema),
@@ -738,7 +624,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       /**
        * 배송완료 처리 — `DISPATCHED`·`DELIVERING`만 넘어간다. 응답의 `autoDecisionDate`가 자동 구매확정 예정일이다
-       * (스토어 설정 `autoConfirmDays`가 0이면 null).
+       * (상점 설정 `autoConfirmDays`가 0이면 null).
        */
       markDelivered: (orderItemId: string, idempotencyKey?: string) =>
         storeHttp.request("POST", path`/order-items/${orderItemId}/delivered`, orderItemSchema, {
@@ -827,7 +713,7 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /**
-     * 구매자 로그인 설정 — 이메일·비밀번호 허용, 소셜 공급자 연결. 비밀 값을 다루므로 콘솔에 로그인한 OWNER만 호출할 수 있다
+     * 구매자 로그인 설정 — 이메일·비밀번호 허용, 소셜 공급자 연결. 비밀 값을 다루므로 상점 플랫폼에 로그인한 OWNER만 호출할 수 있다
      */
     loginSettings: {
       get: () => storeHttp.request("GET", "/store/login-settings", loginSettingsSchema),
@@ -855,7 +741,7 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("DELETE", path`/store/auth-providers/${provider}`, loginSettingsSchema),
     },
 
-    /** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(콘솔 OWNER·ADMIN) */
+    /** 구매자 관리 — 조회 `customer:r`, 탈퇴 처리 `customer:rw`(상점 플랫폼 OWNER·ADMIN) */
     customers: {
       list: (
         params?: PageParams & Omit<z.input<typeof customerListQuerySchema>, "page" | "size">,
@@ -1069,9 +955,9 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /**
-     * 결제(PG) 설정 — **콘솔 OWNER 전용**. ADMIN·STAFF·PAT·M2M·3rd-party 앱 토큰은 스코프가 있어도
-     * 403 `INSUFFICIENT_ROLE`이다(조회 포함). OWNER 여부는 요청 시점의 스토어 멤버십으로 다시 확인하므로
-     * 양도·강등 직후의 옛 storeToken도 403이다(토큰을 재발급받는다). 비밀 값(시크릿 키·API Secret·웹훅 시크릿)은 요청으로만 보내고
+     * 결제(PG) 설정 — **상점 플랫폼 OWNER 전용**. ADMIN·STAFF·PAT·M2M·3rd-party 앱 토큰은 스코프가 있어도
+     * 403 `INSUFFICIENT_ROLE`이다(조회 포함). OWNER 여부는 요청 시점의 상점 멤버십으로 다시 확인하므로
+     * 양도·강등 직후에도 바로 403이다. 비밀 값(시크릿 키·API Secret·웹훅 시크릿)은 요청으로만 보내고
      * 응답에는 `secrets[].masked`(앞 4자리 마스킹)만 나온다.
      */
     paymentSettings: {
@@ -1241,7 +1127,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
     },
 
-    /** API 로그 (보관 7일, 콘솔 OWNER/ADMIN) */
+    /** API 로그 (보관 7일, 상점 플랫폼 OWNER/ADMIN) */
     apiLogs: {
       /** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
       list: (params?: ApiLogListOptions) =>
@@ -1257,7 +1143,7 @@ export function createStoreClient(options: StoreClientOptions) {
       summary: () => storeHttp.request("GET", "/api-logs/summary", apiLogSummarySchema),
     },
 
-    /** 감사 로그 (관리 API 쓰기의 행위자·대상·결과, 콘솔 OWNER/ADMIN, `audit:r`) */
+    /** 감사 로그 (관리 API 쓰기의 행위자·대상·결과, 상점 플랫폼 OWNER/ADMIN, `audit:r`) */
     auditLogs: {
       /** 최신순 커서 페이지네이션. 다음 페이지는 응답의 `nextCursor`를 `cursor`로 넘긴다 */
       list: (params?: AuditLogListOptions) =>
@@ -1272,7 +1158,7 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /**
-     * 승인 요청 — 에이전트의 고위험 쓰기가 202로 보류된 건. 목록·승인·거절은 콘솔 OWNER/ADMIN,
+     * 승인 요청 — 에이전트의 고위험 쓰기가 202로 보류된 건. 목록·승인·거절은 상점 플랫폼 OWNER/ADMIN,
      * 단건 조회는 요청한 토큰도 할 수 있다(상태 확인용).
      */
     approvalRequests: {
@@ -1361,7 +1247,7 @@ export function createStoreClient(options: StoreClientOptions) {
         ),
       /**
        * `POST /v1/storefront/site` (201) — 템플릿으로 사이트를 만들고 v1을 발행한다. 공개 상태는 오픈 준비 중이다.
-       * 사이트를 만드는 유일한 경로다(스토어를 만들어도 사이트는 생기지 않는다). 템플릿은 여기서만 고른다
+       * 사이트를 만드는 유일한 경로다(상점을 만들어도 사이트는 생기지 않는다). 템플릿은 여기서만 고른다
        */
       create: (body: CreateStorefrontSiteRequest) =>
         storeHttp.request("POST", "/storefront/site", storefrontSiteSchema, {
@@ -1412,7 +1298,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       /**
        * `POST /v1/storefront/site/preview-link` — 오픈 준비 중인 사이트를 구성원이 볼 수 있는 5분짜리 링크.
-       * 콘솔에서 로그인한 OWNER·ADMIN만 받는다
+       * 상점 플랫폼에서 로그인한 OWNER·ADMIN만 받는다
        */
       createPreviewLink: (body: CreateStorefrontPreviewLinkRequest = {}) =>
         storeHttp.request("POST", "/storefront/site/preview-link", storefrontPreviewLinkSchema, {
@@ -1470,7 +1356,7 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("DELETE", "/storefront/site/editing", storefrontEditingSchema),
       /**
        * `POST /v1/storefront/site/editing/preview-link` — 편집 미리보기(dev 서버) 5분짜리 링크.
-       * 콘솔에서 로그인한 OWNER·ADMIN만 받는다(에이전트 불가)
+       * 상점 플랫폼에서 로그인한 OWNER·ADMIN만 받는다(에이전트 불가)
        */
       createEditPreviewLink: (body: CreateStorefrontEditPreviewLinkRequest = {}) =>
         storeHttp.request(
@@ -1583,6 +1469,22 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
     },
 
+    subscription: {
+      /**
+       * `GET /v1/store/subscription` — 스코프 `store:r`. 현재 요금제·상태·사용량 기간·한도·이번 기간 사용량.
+       * 결제 수단·청구 금액은 싣지 않는다. 요금제 변경은 상점 플랫폼에서만 한다
+       */
+      get: () => storeHttp.request("GET", "/store/subscription", storeSubscriptionSchema),
+    },
+
+    plans: {
+      /**
+       * `GET /v1/public/plans` — 인증 없음. 공개 요금제의 지금 버전(가격·기능 키 값). 값은 서버가 관리하고 언제든 바뀔 수 있어
+       * 코드에 요금제 수치를 두지 말고 이 값을 읽는다
+       */
+      listPublic: () => storeHttp.request("GET", "/public/plans", publicPlansSchema),
+    },
+
     store: {
       get: () => storeHttp.request("GET", "/store", storeSchema),
       /**
@@ -1608,7 +1510,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       /**
        * `POST /v1/store/invitations` (201) — 스코프 `member:rw`. 초대 메일을 보낸다. 발송 결과는 응답의
-       * `deliveryStatus`다(발송이 실패해도 초대는 만들어진다). 스토어·초대한 사람·받는 주소별 발송 한도가 있다(429, `details.limit`).
+       * `deliveryStatus`다(발송이 실패해도 초대는 만들어진다). 상점·초대한 사람·받는 주소별 발송 한도가 있다(429, `details.limit`).
        */
       invite: (body: InviteMemberRequest) =>
         storeHttp.request("POST", "/store/invitations", invitationSchema, {

package/src/http.ts

@@ -74,7 +74,7 @@ export const APPROVAL_ALREADY_DECIDED_CODE = "APPROVAL_ALREADY_DECIDED";
  * 성공 값으로 돌려주지 않는다 — 돌려주면 호출부가 승인 요청을 상품·주문으로 읽는다.
  *
  * - `code = APPROVAL_REQUIRED`(202): 에이전트의 고위험 쓰기가 보류됐다. 아직 아무것도 바뀌지 않았다.
- *   셀러가 콘솔(`approval.approvalUrl`)에서 승인하면 서버가 원 요청을 실행한다. 같은 요청을 다시 보내지 말고
+ *   셀러가 상점 플랫폼(`approval.approvalUrl`)에서 승인하면 서버가 원 요청을 실행한다. 같은 요청을 다시 보내지 말고
  *   `approvalRequests.get(approvalId)`로 결과를 확인한다.
  * - `code = APPROVAL_ALREADY_DECIDED`(200): 같은 멱등키로 보낸 요청의 승인이 이미 끝났다. `status`가
  *   `SUCCEEDED`·`FAILED`·`UNKNOWN`이면 실행 결과(`approval.result`)를 보고, `REJECTED`·`EXPIRED`면 새 멱등키로 다시 요청한다.

package/src/index.ts

@@ -12,13 +12,11 @@ export {
   buildAuthorizeUrl,
   createPkcePair,
   exchangeAuthorizationCode,
-  exchangeStoreTokenViaOAuth,
   type OAuthTokenResponse,
   oauthTokenResponseSchema,
   refreshUserToken,
 } from "./oauth";
 export * from "./schemas/analytics";
-export * from "./schemas/api-client";
 export * from "./schemas/api-log";
 export * from "./schemas/audit";
 export * from "./schemas/auth";
@@ -27,6 +25,7 @@ export * from "./schemas/claim";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
 export * from "./schemas/customer";
+export * from "./schemas/customer-delegation";
 export * from "./schemas/fulfillment";
 export * from "./schemas/login";
 export * from "./schemas/misc";
@@ -40,6 +39,7 @@ export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
 export * from "./schemas/store";
 export * from "./schemas/storefront-hosting";
+export * from "./schemas/subscription";
 export * from "./schemas/telemetry";
 export * from "./schemas/upload";
 export * from "./schemas/webhook-event";
@@ -48,6 +48,7 @@ export {
   createStoreSession,
   type SessionStorage,
   STORE_SESSION_KEYS,
+  type StoreAuthServer,
   type StoreSession,
   type StoreSessionOptions,
 } from "./session";