connectbase-client 6.0.0 → 6.2.0

package/dist/index.mjs

@@ -1637,20 +1637,48 @@ var AuthAPI = class {
     });
   }
   /**
-   * 앱 멤버 회원가입 (아이디/비밀번호 기반)
+   * 앱 멤버 회원가입 (아이디/이메일 + 비밀번호 기반)
    * 앱에 새로운 멤버를 등록합니다.
    *
+   * `login_id` 와 `email` 중 **최소 하나**는 있어야 합니다. 어느 쪽을 주느냐에 따라
+   * 만들어지는 로그인 수단이 달라집니다 — 표는 {@link MemberSignUpRequest} 참고.
+   *
+   * `email` 을 함께 저장해야 나중에 {@link AuthAPI.requestPasswordReset} 로 비밀번호를
+   * 복구할 수 있습니다. `login_id` 만으로 가입한 멤버는 복구 수단이 없습니다.
+   *
+   * 이메일을 넘겨도 **인증 메일이 자동 발송되지는 않습니다.** 발신 주소가 플랫폼 단일
+   * 주소라 앱이 요청하지 않은 메일을 보내지 않는다는 정책입니다 — 필요하면 가입 직후
+   * {@link AuthAPI.sendEmailVerification} 을 직접 호출하세요.
+   *
    * @example
    * ```typescript
+   * // 기존 방식 — 아이디만 (동작 그대로, 단 비밀번호 복구 불가)
    * const result = await client.auth.signUpMember({
    *     login_id: 'myuser123',
    *     password: 'password123',
    *     nickname: 'John'
    * })
-   * console.log('가입 완료:', result.member_id)
+   *
+   * // 아이디 + 복구용 이메일 (로그인은 여전히 login_id 로)
+   * await client.auth.signUpMember({
+   *     login_id: 'myuser123',
+   *     email: 'john@example.com',
+   *     password: 'password123'
+   * })
+   *
+   * // 이메일만 — 이메일이 곧 로그인 아이디
+   * await client.auth.signUpMember({
+   *     email: 'john@example.com',
+   *     password: 'password123'
+   * })
    * ```
    */
   async signUpMember(data) {
+    if (!data.login_id && !data.email) {
+      throw new Error(
+        "signUpMember requires at least one of login_id or email."
+      );
+    }
     const response = await this.http.post(
       "/v1/public/app-members/signup",
       data,
@@ -1670,19 +1698,34 @@ var AuthAPI = class {
     return response;
   }
   /**
-   * 앱 멤버 로그인 (아이디/비밀번호 기반)
+   * 앱 멤버 로그인 (아이디 또는 이메일 + 비밀번호)
    * 기존 멤버로 로그인합니다.
    *
+   * `login_id` 가 1순위 조회 키이고, `email` 은 이메일로 가입한 멤버를 위한 별칭입니다.
+   * 서버는 USERNAME 을 먼저 찾고 없을 때만 EMAIL 로 폴백하므로 **기존 `login_id` 호출은
+   * 동작이 그대로**입니다. 둘 다 비어 있으면 400 입니다.
+   *
    * @example
    * ```typescript
+   * // 아이디로 로그인 (기존 방식)
    * const result = await client.auth.signInMember({
    *     login_id: 'myuser123',
    *     password: 'password123'
    * })
-   * console.log('로그인 성공:', result.member_id)
+   *
+   * // 이메일로 로그인
+   * await client.auth.signInMember({
+   *     email: 'john@example.com',
+   *     password: 'password123'
+   * })
    * ```
    */
   async signInMember(data) {
+    if (!data.login_id && !data.email) {
+      throw new Error(
+        "signInMember requires at least one of login_id or email."
+      );
+    }
     const response = await this.http.post(
       "/v1/public/app-members/signin",
       data,
@@ -1701,6 +1744,169 @@ var AuthAPI = class {
     this.notifyVisitorTracker(response.member_id);
     return response;
   }
+  // ── 자격증명 복구/변경 ────────────────────────────────────────────────────
+  //
+  // # 메일 링크는 "앱이 운영하는 페이지"를 거친다
+  //
+  // 재설정/인증 메일의 링크는 이 API 를 직접 열지 않습니다. 브라우저 주소창으로는
+  // `X-Public-Key` 헤더를 붙일 수 없기 때문입니다. 링크는 앱의 페이지(= SDK 가 이미
+  // 초기화돼 있는 곳)로 가고, 그 페이지가 쿼리에서 `token` 을 꺼내 아래 confirm 메서드를
+  // 호출하는 구조입니다.
+  //
+  // 그래서 `redirect_url` 로 넘길 주소는 **앱에 등록된 도메인이어야 합니다**
+  // (자세한 규칙은 {@link MemberRedirectOption}). 도메인을 등록하지 않으면 링크가
+  // 플랫폼 기본 페이지로 폴백합니다.
+  /**
+   * 비밀번호 재설정 메일을 보냅니다. (로그인 불필요)
+   *
+   * # 계정 열거 방지 — 응답으로는 아무것도 알 수 없다
+   *
+   * 가입되지 않은 이메일이든, 소셜 전용 계정(비밀번호 없음)이든, 정지된 멤버든
+   * **똑같은 200 과 똑같은 문구**가 돌아옵니다. 메일이 실제로 나갔는지 여부는 응답으로
+   * 판별할 수 없습니다 — "가입 여부 확인" 용도로 쓸 수 없다는 뜻이며, 의도된 설계입니다.
+   * UI 에서도 "가입된 계정이라면 메일을 보냈습니다" 처럼 안내하세요.
+   *
+   * 메일 링크의 토큰은 **1시간** 만료이고 **1회만** 쓸 수 있습니다.
+   *
+   * @example
+   * ```typescript
+   * // 앱이 자체 재설정 페이지를 운영하는 경우 (도메인 등록 선행 필수)
+   * await client.auth.requestPasswordReset({
+   *     email: 'john@example.com',
+   *     redirect_url: 'https://myapp.com/reset-password'
+   * })
+   * toast('가입된 계정이라면 재설정 링크를 보냈습니다')
+   * ```
+   */
+  async requestPasswordReset(data) {
+    return this.http.post(
+      "/v1/public/app-members/password-reset/request",
+      data,
+      { skipAuth: true }
+    );
+  }
+  /**
+   * 재설정 토큰으로 새 비밀번호를 확정합니다. (로그인 불필요)
+   *
+   * `redirect_url` 페이지의 `?token=` 쿼리 값을 그대로 넘기면 됩니다.
+   *
+   * 성공하면 **그 멤버의 모든 세션이 서버에서 폐기**됩니다. 다른 기기 로그인까지 전부
+   * 끊기며, 이 SDK 인스턴스에 남아 있던 토큰도 함께 정리하므로 새 비밀번호로 다시
+   * 로그인해야 합니다.
+   *
+   * 토큰이 만료(1시간)됐거나 이미 사용됐거나 위조/타앱 토큰이면 400 이 납니다. 사유는
+   * 구분되지 않습니다 — 토큰을 탐색하는 단서를 주지 않기 위해서입니다.
+   *
+   * @example
+   * ```typescript
+   * const token = new URLSearchParams(location.search).get('token')
+   * if (!token) return
+   * try {
+   *     await client.auth.confirmPasswordReset({ token, new_password: 'newpass123' })
+   *     location.href = '/login'
+   * } catch (e) {
+   *     // 만료, 이미 사용됨, 잘못된 링크가 모두 여기로 온다
+   *     alert('링크가 만료되었거나 이미 사용되었습니다. 재설정을 다시 요청해 주세요.')
+   * }
+   * ```
+   */
+  async confirmPasswordReset(data) {
+    const response = await this.http.post(
+      "/v1/public/app-members/password-reset/confirm",
+      data,
+      { skipAuth: true }
+    );
+    this.http.clearTokens();
+    this.notifyVisitorTracker(null);
+    return response;
+  }
+  /**
+   * 로그인한 멤버가 현재 비밀번호를 확인하고 새 비밀번호로 바꿉니다. (AppMember 토큰 필요)
+   *
+   * `confirmPasswordReset` 과 마찬가지로 성공 시 **전 세션이 폐기**되고 로컬 토큰도
+   * 정리됩니다. 호출한 클라이언트도 재로그인이 필요합니다.
+   *
+   * @example
+   * ```typescript
+   * await client.auth.changePassword({
+   *     current_password: 'oldpass123',
+   *     new_password: 'newpass123'
+   * })
+   * // 세션이 끊겼으므로 로그인 화면으로
+   * location.href = '/login'
+   * ```
+   */
+  async changePassword(data) {
+    const response = await this.http.post(
+      "/v1/public/app-members/me/password",
+      data
+    );
+    this.http.clearTokens();
+    this.notifyVisitorTracker(null);
+    return response;
+  }
+  /**
+   * 로그인한 멤버에게 이메일 인증 메일을 보냅니다. (AppMember 토큰 필요)
+   *
+   * 가입 시 자동 발송되지 않으므로, 인증이 필요한 앱은 이 메서드를 **직접** 불러야 합니다
+   * (예: 가입 직후, 또는 설정 화면의 "인증 메일 다시 보내기" 버튼).
+   *
+   * 메일 링크의 토큰은 **24시간** 만료이고 **1회만** 쓸 수 있습니다.
+   *
+   * 이메일 인증은 **로그인의 전제 조건이 아닙니다** — 인증하지 않아도 로그인은 됩니다.
+   * 인증 여부로 기능을 제한할지는 앱이 `getMe()` 등으로 확인해 스스로 정합니다.
+   *
+   * @example
+   * ```typescript
+   * await client.auth.sendEmailVerification({
+   *     redirect_url: 'https://myapp.com/verify-email'
+   * })
+   *
+   * // redirect_url 없이 — 플랫폼 기본 페이지 링크로 발송된다
+   * await client.auth.sendEmailVerification()
+   * ```
+   */
+  async sendEmailVerification(data) {
+    return this.http.post(
+      "/v1/public/app-members/me/email-verification/request",
+      data ?? {}
+    );
+  }
+  /**
+   * 인증 토큰으로 이메일 인증을 확정합니다. (로그인 불필요)
+   *
+   * 메일 링크가 연 페이지에서 `?token=` 을 꺼내 그대로 넘깁니다. 링크를 누른 사람이 그
+   * 앱에 로그인해 있지 않아도(다른 기기의 메일 앱에서 열어도) 동작합니다.
+   *
+   * 만료(24시간), 이미 사용됨, 위조 토큰은 모두 400 이며 사유가 구분되지 않습니다.
+   *
+   * @example
+   * ```typescript
+   * const token = new URLSearchParams(location.search).get('token')
+   * if (!token) return
+   * try {
+   *     const r = await client.auth.confirmEmailVerification({ token })
+   *     console.log(r.email, r.is_email_verified) // true
+   * } catch {
+   *     alert('인증 링크가 만료되었거나 이미 사용되었습니다.')
+   * }
+   * ```
+   */
+  async confirmEmailVerification(data) {
+    const response = await this.http.post(
+      "/v1/public/app-members/email-verification/confirm",
+      data,
+      { skipAuth: true }
+    );
+    assertShape(
+      response,
+      {
+        member_id: { type: "string-or-number" }
+      },
+      "auth.confirmEmailVerification"
+    );
+    return response;
+  }
   /**
    * 현재 로그인한 멤버 정보 조회
    * custom_data를 포함한 멤버 정보를 반환합니다.
@@ -1864,6 +2070,109 @@ var AuthAPI = class {
       this.notifyVisitorTracker(null);
     }
   }
+  // ── 활성 세션(로그인된 기기) 관리 ────────────────────────────────────────
+  //
+  // 대상은 언제나 **로그인한 본인**이다. 세 메서드 모두 사용자 식별자를 받지 않는다 —
+  // 누구의 세션인지는 서버가 검증된 토큰에서 정하고, 요청은 정할 수 없다.
+  //
+  // 폐기는 되돌릴 수 없다. 다만 이미 발급된 액세스 토큰은 만료(최대 1시간)까지 유효하므로,
+  // 끊긴 기기가 곧바로 모든 호출에 실패하지는 않는다. 즉시 차단이 필요하면 앱이 서버
+  // 측에서 회원을 정지시켜야 한다.
+  /**
+   * 로그인된 기기(활성 세션) 목록을 조회합니다.
+   *
+   * 현재 세션이 맨 앞에 오고, 나머지는 최근 사용 순입니다. 응답에는 토큰도 평문 IP 도
+   * 담기지 않습니다.
+   *
+   * **`current` 를 화면에 반드시 표시하세요.** 구분이 없으면 사용자가 자기가 쓰고 있는
+   * 기기를 끊고 영문도 모른 채 로그아웃됩니다. refresh 쿠키가 없는 환경에서는 서버가
+   * 현재 세션을 특정하지 못해 `current` 가 어느 항목에도 붙지 않을 수 있습니다.
+   *
+   * @example
+   * ```typescript
+   * const { sessions } = await cb.auth.listSessions()
+   * for (const s of sessions) {
+   *     console.log(s.browser, s.os, s.location, s.current ? '(이 기기)' : '')
+   * }
+   * ```
+   */
+  async listSessions() {
+    const response = await this.http.get(
+      "/v1/public/app-members/me/sessions"
+    );
+    assertShape(
+      response,
+      {
+        sessions: { type: "array" }
+      },
+      "auth.listSessions"
+    );
+    return response;
+  }
+  /**
+   * 기기 하나를 로그아웃시킵니다. `sessionId` 는 `listSessions()` 가 돌려준 `session_id`.
+   *
+   * 남의 세션 식별자를 넣으면 404 입니다 — 존재 여부조차 구분해 알려주지 않습니다.
+   * 이미 끝난 세션도 같은 404 입니다.
+   *
+   * **현재 세션을 지목하면 그 자리에서 로그아웃됩니다.** 서버가 refresh 쿠키를 함께
+   * 만료시키므로 로컬 토큰도 정리합니다 — 이 경우 앱은 로그인 화면으로 보내야 합니다.
+   * 그렇지 않은 기기를 끊는 것은 현재 세션에 영향을 주지 않습니다.
+   *
+   * @example
+   * ```typescript
+   * const target = sessions.find((s) => !s.current)
+   * if (target) await cb.auth.revokeSession(target.session_id)
+   * ```
+   */
+  async revokeSession(sessionId) {
+    const current = await this.isCurrentSession(sessionId);
+    const response = await this.http.delete(
+      `/v1/public/app-members/me/sessions/${encodeURIComponent(sessionId)}`
+    );
+    if (current) {
+      this.http.clearTokens();
+      this.notifyVisitorTracker(null);
+    }
+    return response;
+  }
+  /**
+   * **현재 기기만 남기고** 나머지 기기에서 모두 로그아웃합니다.
+   *
+   * 자기 세션까지 포함한 전체 로그아웃은 `signOut()` 입니다 — 자격증명 유출 대응처럼
+   * 모든 기기를 내보내야 하는 상황에서는 그쪽을 쓰세요.
+   *
+   * refresh 쿠키가 없어 서버가 현재 세션을 특정하지 못하면 이 호출은 **실패합니다**
+   * (400). 기준점 없이 진행하면 사용자가 의도하지 않은 자기 세션 종료가 함께 일어나기
+   * 때문입니다. 그 경우 `signOut()` 후 재로그인을 안내하세요.
+   *
+   * 반환되는 `revoked` 는 토큰 수가 아니라 **끊긴 기기 수** 입니다.
+   *
+   * @example
+   * ```typescript
+   * const { revoked } = await cb.auth.revokeOtherSessions()
+   * toast(`${revoked}개 기기에서 로그아웃했습니다`)
+   * ```
+   */
+  async revokeOtherSessions() {
+    return this.http.delete(
+      "/v1/public/app-members/me/sessions"
+    );
+  }
+  /**
+   * 폐기 대상이 현재 세션인지 미리 확인한다. 목록 조회가 실패하면 false 로 떨어져
+   * 폐기 자체는 진행한다 — 판정 실패로 사용자의 로그아웃 요청을 막을 이유가 없다.
+   */
+  async isCurrentSession(sessionId) {
+    try {
+      const { sessions } = await this.listSessions();
+      return sessions.some(
+        (s) => s.session_id === sessionId && s.current === true
+      );
+    } catch {
+      return false;
+    }
+  }
 };
 
 // src/api/database.ts
@@ -6582,6 +6891,199 @@ var OAuthAPI = class {
   }
 };
 
+// src/api/organizations.ts
+var OrganizationsAPI = class {
+  constructor(http) {
+    this.http = http;
+    /** 조직 라우트는 `/v1/public` 아래에만 있습니다. */
+    this.prefix = "/v1/public/organizations";
+  }
+  // =====================
+  // 조직
+  // =====================
+  /**
+   * 조직을 만듭니다. **만든 사람이 자동으로 `owner`** 가 됩니다.
+   *
+   * @example
+   * ```typescript
+   * const org = await cb.organizations.create({ name: '우리 팀' })
+   * // slug 를 생략하면 name 에서 파생되고, 충돌하면 짧은 접미사가 붙는다
+   * ```
+   */
+  async create(data) {
+    return this.http.post(this.prefix, data);
+  }
+  /**
+   * 내가 속한 조직 목록. 조직 전환 UI 를 그릴 때 씁니다.
+   *
+   * 각 항목의 `my_role` 이 채워집니다. `member_count` 는 목록에서는 실리지 않습니다
+   * (조직마다 COUNT 를 돌면 N+1 이라 상세 조회에서만 채워집니다).
+   */
+  async listMine() {
+    const res = await this.http.get(
+      this.prefix
+    );
+    return res.organizations ?? [];
+  }
+  /**
+   * 조직 상세. `my_role` 과 `member_count` 가 함께 실립니다.
+   *
+   * 내가 속하지 않은 조직은 **403 이 아니라 404** 입니다 — 403 을 주면 그것만으로 그 조직이
+   * 실재한다는 사실이 새어 조직 ID 열거가 가능해지기 때문입니다.
+   */
+  async get(organizationId) {
+    return this.http.get(`${this.prefix}/${organizationId}`);
+  }
+  /**
+   * 조직 정보 수정.
+   *
+   * **`slug` 는 바꿀 수 없습니다** — 변경을 허용하면 조직 URL 과 외부 참조가 조용히 깨지고,
+   * 놓아준 slug 를 다른 조직이 선점해 다른 조직의 페이지가 열립니다.
+   */
+  async update(organizationId, data) {
+    return this.http.patch(
+      `${this.prefix}/${organizationId}`,
+      data
+    );
+  }
+  /** 조직 삭제. */
+  async delete(organizationId) {
+    return this.http.delete(
+      `${this.prefix}/${organizationId}`
+    );
+  }
+  // =====================
+  // 멤버
+  // =====================
+  /**
+   * 조직 멤버 목록.
+   *
+   * 닉네임/이메일 같은 **프로필은 실리지 않습니다** — 조직에 초대되기만 하면 다른 구성원의
+   * 이메일을 전부 수집할 수 있게 되기 때문입니다. 프로필이 필요하면 `member_id` 로
+   * `cb.appMembers.*` 를 조회하세요.
+   */
+  async listMembers(organizationId, params) {
+    const query = new URLSearchParams();
+    if (params?.limit !== void 0) query.set("limit", String(params.limit));
+    if (params?.offset !== void 0)
+      query.set("offset", String(params.offset));
+    const qs = query.toString();
+    return this.http.get(
+      `${this.prefix}/${organizationId}/members${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * 멤버의 조직 역할 변경.
+   *
+   * 소유자는 별도 컬럼이 아니라 `role === 'owner'` 인 행에서 파생되므로, 마지막 owner 의
+   * 역할을 내리는 것은 거부됩니다 (403).
+   */
+  async updateMemberRole(organizationId, memberId, role) {
+    return this.http.patch(
+      `${this.prefix}/${organizationId}/members/${memberId}`,
+      { role }
+    );
+  }
+  /**
+   * 멤버 제거. **본인 ID 를 넘기면 조직 탈퇴**입니다.
+   *
+   * 마지막 owner 는 제거할 수 없습니다 (403) — 소유자 없는 조직은 아무도 삭제할 수 없게
+   * 되기 때문입니다.
+   */
+  async removeMember(organizationId, memberId) {
+    return this.http.delete(
+      `${this.prefix}/${organizationId}/members/${memberId}`
+    );
+  }
+  // =====================
+  // 초대
+  // =====================
+  /**
+   * 초대 생성.
+   *
+   * **평문 토큰은 이 응답에서만 볼 수 있습니다** (DB 에는 SHA-256 만 남습니다).
+   * **초대 메일 발송은 플랫폼이 대신하지 않습니다** — 앱마다 문안과 발송 채널이 다르므로,
+   * 받은 토큰을 초대 대상에게 전달하는 것은 앱의 몫입니다.
+   *
+   * @example
+   * ```typescript
+   * const { invitation, token } = await cb.organizations.createInvitation(orgId, {
+   *     email: 'teammate@example.com',
+   *     role: 'member',
+   * })
+   * // token 을 담은 초대 링크를 앱이 직접 발송한다
+   * await sendMyInviteMail(invitation.email, `https://myapp.com/join?token=${token}`)
+   * ```
+   */
+  async createInvitation(organizationId, data) {
+    return this.http.post(
+      `${this.prefix}/${organizationId}/invitations`,
+      data
+    );
+  }
+  /** 조직의 초대 목록. 평문 토큰은 실리지 않습니다. */
+  async listInvitations(organizationId) {
+    const res = await this.http.get(`${this.prefix}/${organizationId}/invitations`);
+    return res.invitations ?? [];
+  }
+  /** 초대 취소. */
+  async revokeInvitation(organizationId, invitationId) {
+    return this.http.delete(
+      `${this.prefix}/${organizationId}/invitations/${invitationId}`
+    );
+  }
+  /**
+   * 초대 토큰으로 조직에 합류합니다. 조직 ID 를 몰라도 됩니다.
+   *
+   * 수락자의 이메일은 **로그인한 회원 토큰의 클레임**에서 가져오므로, 초대 대상과 다른
+   * 계정으로 로그인한 상태면 거부됩니다 (403).
+   * 없는 토큰/만료/이미 사용됨/취소됨은 **구분하지 않고 404** 입니다 (토큰 추측 방지).
+   */
+  async acceptInvitation(token) {
+    return this.http.post(
+      `${this.prefix}/invitations/accept`,
+      { token }
+    );
+  }
+  // =====================
+  // 조직 컨텍스트 (조직 전환)
+  // =====================
+  /**
+   * 조직을 전환합니다 — 활성 조직이 실린 새 액세스 토큰을 받아 **SDK 에 자동 적용**합니다.
+   *
+   * 데이터베이스 보안 규칙(RLS)의 `auth.org_id` / `auth.org_role` 을 채우는 **유일한
+   * 경로**이며, 호출할 때마다 소속과 역할을 DB 에서 다시 확인합니다.
+   *
+   * ## 반드시 주기적으로 다시 호출하세요
+   *
+   * 조직 컨텍스트의 수명은 반환값의 `org_context_expires_in`(기본 600초) 입니다. 액세스
+   * 토큰(1시간)과 독립적이라, 만료되어도 401 이 나지 않고 조직 규칙만 조용히 거부됩니다.
+   *
+   * ## 세션을 연장하지 않습니다
+   *
+   * 새 토큰의 수명은 `min(1시간, 지금 토큰의 남은 수명)` 입니다. 전환으로 세션을 무한
+   * 연장할 수 없게 하기 위한 제약이며, refresh token 은 건드리지 않습니다. 토큰 회전이
+   * 일어나면 조직 컨텍스트는 사라지므로 다시 호출해야 합니다.
+   *
+   * @example
+   * ```typescript
+   * const ctx = await cb.organizations.switchTo(orgId)
+   * console.log(ctx.role, ctx.org_context_expires_in)
+   * // 이 시점부터 DB 요청은 auth.org_id 가 채워진 상태로 나간다
+   * ```
+   */
+  async switchTo(organizationId) {
+    const ctx = await this.http.post(
+      `${this.prefix}/${organizationId}/context`,
+      {}
+    );
+    if (ctx?.access_token) {
+      this.http.setAccessToken(ctx.access_token);
+    }
+    return ctx;
+  }
+};
+
 // src/api/payment.ts
 var PaymentAPI = class {
   constructor(http) {
@@ -6887,6 +7389,35 @@ var PublicKeyAPI = class {
     this.ensureServerAuth("deletePublicKey");
     await this.http.delete(`/v1/apps/${appId}/public-keys/${keyId}`);
   }
+  /**
+   * Public Key 를 **무중단 회전**합니다 (management_scope: `publickey:manage`)
+   *
+   * 새 키를 발급하고 옛 키는 유예 기간 동안 함께 유효하게 둔 뒤 만료시킵니다. 옛 키의
+   * 스코프와 `payment_mode` 는 새 키가 물려받습니다 — 리셋되면 읽기 전용 키가 회전 한 번에
+   * 전권이 되기 때문입니다.
+   *
+   * **반환되는 `new_key.key` 는 이 응답에서만 볼 수 있습니다.**
+   *
+   * @param appId 앱 ID
+   * @param keyId 회전할 Public Key ID
+   * @param data 유예 기간(기본 24시간, 상한 720시간)과 새 키 이름
+   *
+   * @example
+   * ```typescript
+   * const rotated = await cb.publicKey.rotatePublicKey('app-id', 'key-id', {
+   *   grace_period_hours: 72,
+   * })
+   * // 1. rotated.new_key.key 를 배포 파이프라인에 반영
+   * // 2. rotated.previous_key_expires_at 전에 모든 클라이언트 배포를 끝낸다
+   * ```
+   */
+  async rotatePublicKey(appId, keyId, data) {
+    this.ensureServerAuth("rotatePublicKey");
+    return this.http.post(
+      `/v1/apps/${appId}/public-keys/${keyId}/rotate`,
+      data ?? {}
+    );
+  }
 };
 
 // src/api/push.ts
@@ -7265,13 +7796,13 @@ var QueueAPI = class {
     this.http = http;
   }
   /**
-   * 메시지 발행
+   * 메시지 발행 — 엔드유저 동작. 퍼블릭 키만으로 동작합니다.
    */
   async publish(queueID, data) {
     return this.http.post(`/v1/public/queues/${queueID}/messages`, data);
   }
   /**
-   * 배치 메시지 발행 (최대 100개)
+   * 배치 메시지 발행 (최대 100개) — 엔드유저 동작. 퍼블릭 키만으로 동작합니다.
    */
   async publishBatch(queueID, data) {
     return this.http.post(`/v1/public/queues/${queueID}/messages/batch`, data);
@@ -7279,6 +7810,9 @@ var QueueAPI = class {
   /**
    * 메시지 소비 (Pull 방식)
    *
+   * **워커 동작 — Secret Key 필수.** `new ConnectBase({ publicKey, secretKey })` 로 만든
+   * 서버사이드 클라이언트로 호출하세요. 퍼블릭 키만이면 401 `SECRET_KEY_REQUIRED`.
+   *
    * auto_ack=false(기본값): 명시적 Ack 필요. 응답의 ack_token을 ack() 호출 시 전달.
    * auto_ack=true: 즉시 자동 Ack (at-most-once, 유실 가능)
    */
@@ -7306,6 +7840,8 @@ var QueueAPI = class {
   /**
    * 메시지 처리 완료 확인 (Ack)
    *
+   * **워커 동작 — Secret Key 필수.** 퍼블릭 키만이면 401 `SECRET_KEY_REQUIRED`.
+   *
    * ackToken: auto_ack=false 소비 시 반환된 ack_token. 생략 시 message_ids로만 확인.
    */
   async ack(queueID, messageIds, ackToken) {
@@ -7317,6 +7853,8 @@ var QueueAPI = class {
   }
   /**
    * 메시지 재시도 요청 (Nack)
+   *
+   * **워커 동작 — Secret Key 필수.** 퍼블릭 키만이면 401 `SECRET_KEY_REQUIRED`.
    */
   async nack(queueID, messageId, options) {
     return this.http.post(
@@ -7325,7 +7863,9 @@ var QueueAPI = class {
     );
   }
   /**
-   * 큐 정보 조회
+   * 큐 정보 조회 (큐 목록/깊이 등 운영 정보)
+   *
+   * **워커 동작 — Secret Key 필수.** 퍼블릭 키만이면 401 `SECRET_KEY_REQUIRED`.
    */
   async getInfo(queueID) {
     return this.http.get(`/v1/public/queues/${queueID}`);
@@ -9090,6 +9630,10 @@ var StorageAPI = class {
   /**
    * 파일 목록 조회
    *
+   * 접근 수준이 `private` 인 스토리지에서는 **자기가 올린 파일만** 반환하며, 멤버 토큰 없이
+   * 호출하면 401 이다 (빈 배열이 아니라 에러다 — 빈 목록은 "스토리지가 비었다" 와 구분되지
+   * 않아 원인을 찾을 수 없기 때문). `shared` / `public_read` 는 종전대로 전체를 반환한다.
+   *
    * @param storageId - 파일 스토리지 ID
    * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
    *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
@@ -9116,6 +9660,12 @@ var StorageAPI = class {
    *
    * 서버를 거치지 않고 Object Storage에 직접 업로드합니다.
    *
+   * `Authorization: Bearer <AppMember 토큰>` 을 함께 보내면 업로드한 파일이 **그 멤버에게
+   * 귀속**되어, 이후 그 멤버(와 앱 관리자)만 지울 수 있다. 토큰 없이 올린 파일은 귀속이 없어
+   * `shared` 스토리지에서는 누구나 지울 수 있으므로, 사용자 업로드를 받는 앱이라면 로그인
+   * 세션과 함께 호출하는 것을 권장한다. 접근 수준이 `private` 인 스토리지는 멤버 토큰이 없으면
+   * 401 이다.
+   *
    * 3번째 인자는 부모 폴더 ID(문자열) 또는 옵션 객체를 받습니다. 옵션으로
    * `onProgress` 콜백을 넘기면 업로드 진행률(%)을 실시간으로 받을 수 있습니다
    * (브라우저 환경). 기존 `uploadFile(id, file, 'folder-id')` 호출과 하위 호환됩니다.
@@ -9185,6 +9735,10 @@ var StorageAPI = class {
   }
   /**
    * 폴더 생성
+   *
+   * 업로드와 같은 귀속 규칙이 적용된다 — 멤버 토큰과 함께 만들면 그 멤버 소유가 된다.
+   * 폴더 삭제는 CASCADE 라, 폴더 안에 **남이 올린 파일이 하나라도 있으면** 폴더 소유자라도
+   * 지울 수 없다(403).
    */
   async createFolder(storageId, data) {
     const prefix = this.getPublicPrefix();
@@ -9195,6 +9749,13 @@ var StorageAPI = class {
   }
   /**
    * 파일/폴더 삭제
+   *
+   * **업로더 본인 또는 앱 관리자만** 지울 수 있다. 남의 파일이면 403
+   * (`이 파일의 업로더만 수정/삭제할 수 있습니다`), 애초에 볼 수 없는 파일이면 404 다.
+   *
+   * 운영 도구처럼 앱의 모든 파일을 지워야 하는 코드라면 `Authorization: Bearer cb_sk_...`
+   * (Secret Key)를 함께 보낸다. Secret Key 는 브라우저 번들에 넣으면 안 되므로 서버 쪽에서만
+   * 사용한다.
    */
   async deleteFile(storageId, fileId) {
     const prefix = this.getPublicPrefix();
@@ -9252,6 +9813,10 @@ var StorageAPI = class {
    * 같은 경로에 파일이 이미 존재하면 덮어쓰기합니다.
    * URL이 변경되지 않아 고정 URL이 필요한 경우에 유용합니다.
    *
+   * **덮어쓰기는 삭제와 같은 권한을 요구한다.** URL 은 그대로 둔 채 내용만 바뀌므로, 소유권
+   * 검사가 없으면 사이트가 참조 중인 이미지를 임의 콘텐츠로 갈아치울 수 있기 때문이다.
+   * 기존 파일의 업로더 본인이나 앱 관리자가 아니면 403 이다.
+   *
    * @example
    * ```ts
    * // 프로필 이미지 업로드 (항상 같은 URL 유지)
@@ -9564,7 +10129,29 @@ var SubscriptionAPI = class {
   /**
    * 빌링키 삭제
    *
+   * **PG 쪽 등록까지 지워졌는지는 프로바이더마다 다릅니다.** 반환값의 `provider_revoked` 를
+   * 반드시 확인하세요 — `false` 면 Connect Base 기록만 지워졌고 PG 등록은 남아 있습니다.
+   *
+   * | 프로바이더 | PG 해지 | 동작 |
+   * |-----------|---------|------|
+   * | `toss` | O | 토스 빌링키 삭제 API 호출. PG 삭제가 실패하면 DB 행도 지우지 않고 에러 |
+   * | `payapp` / `paypal` / `paddle` / `stripe` | X | "결제수단 삭제" API 가 없어 기록만 삭제. `provider_revoked: false` + `provider_revoke_note` |
+   *
+   * 살아 있는 구독(`active` / `trial` / `paused` / `past_due`)이 그 빌링키를 물고 있으면
+   * PG 해지 경로가 없는 프로바이더에서는 `409 billing_key_bound_to_subscription` 으로
+   * 거절됩니다 (구독을 먼저 해지하세요). **toss 는 이 검사를 하지 않고 그대로 진행합니다** —
+   * PG 등록이 실제로 사라지므로 청구도 함께 멈추기 때문입니다.
+   *
    * @param billingKeyId - 빌링키 ID
+   * @returns 삭제 결과 (PG 해지 여부 포함)
+   *
+   * @example
+   * ```typescript
+   * const result = await client.subscription.deleteBillingKey(billingKeyId)
+   * if (!result.provider_revoked) {
+   *     alert(result.provider_revoke_note)  // PG 등록이 남아 있음을 사용자에게 알린다
+   * }
+   * ```
    */
   async deleteBillingKey(billingKeyId) {
     const prefix = this.getPublicPrefix();
@@ -10579,6 +11166,19 @@ var VideoAPI = class {
   }
   /**
    * Update video details
+   *
+   * ## 소유권 (2026-09 도입)
+   *
+   * **영상을 올린 멤버 본인 또는 앱 관리자만** 수정할 수 있다. 퍼블릭 키(`cb_pk_*`)는
+   * 브라우저 번들에 실려 배포되는 공개값이라 그것만으로는 남의 영상을 다룰 수 없다.
+   *
+   * - `Authorization: Bearer <AppMember 토큰>` — 그 멤버가 올린 영상만
+   * - `Authorization: Bearer cb_sk_...` (Secret Key, 서버 전용) — 앱의 모든 영상
+   *
+   * 남의 영상이면 403 (`NOT_RESOURCE_OWNER`) 이다.
+   *
+   * 업로더 정보가 없는 **기존 영상**(멤버 토큰 없이 업로드된 것)은 스토리지 접근 수준이
+   * `shared` 일 때 종전대로 수정할 수 있다 — 운영 중인 앱의 동작을 바꾸지 않기 위한 하위호환.
    */
   async update(videoId, data) {
     const prefix = this.getPublicPrefix();
@@ -10586,6 +11186,8 @@ var VideoAPI = class {
   }
   /**
    * Delete a video
+   *
+   * `update()` 와 동일한 소유권 규칙이 적용된다 — 업로더 본인 또는 앱 관리자만 삭제할 수 있다.
    */
   async delete(videoId) {
     const prefix = this.getPublicPrefix();
@@ -11729,6 +12331,7 @@ function fetchCredentialsForPath(url) {
   return path.startsWith("/v1/public/") || path.startsWith("/v1/proxy/") ? "omit" : "include";
 }
 var TOKEN_STORAGE_KEY = "cb_auth_tokens";
+var NO_COOKIE_SESSION_COOLDOWN_MS = 6e4;
 function gatewayCodeFromStatus(status) {
   switch (status) {
     case 502:
@@ -11873,6 +12476,7 @@ var HttpClient = class {
     this.config.refreshToken = refreshToken;
     this.persistTokens();
     this.markSessionHint();
+    this.clearNoCookieSessionMark();
   }
   clearTokens() {
     this.config.accessToken = void 0;
@@ -11880,6 +12484,20 @@ var HttpClient = class {
     this.removePersistedTokens();
     this.clearSessionHint();
   }
+  /**
+   * Access Token 만 교체한다 (refresh token 은 건드리지 않는다).
+   *
+   * 조직 컨텍스트 발급(`POST /v1/public/organizations/:orgID/context`)처럼 **새 액세스
+   * 토큰만 돌려주는** 엔드포인트를 위한 것이다. 그 엔드포인트는 refresh token 을 회전시키지
+   * 않으므로 `setTokens()` 로 빈 refresh token 을 덮어쓰면 세션 복구가 깨진다.
+   *
+   * 세션이 새로 생기는 것이 아니므로 세션 힌트/쿠키 없음 마커는 건드리지 않는다 — 그 두
+   * 마커는 로그인/재발급이 소유한다.
+   */
+  setAccessToken(accessToken) {
+    this.config.accessToken = accessToken;
+    this.persistTokens();
+  }
   // ===== 세션 힌트 =====
   //
   // "이 origin 에서 이 앱으로 로그인한 적이 있다"는 boolean 마커 (토큰 아님 — 민감정보 없음).
@@ -11916,6 +12534,45 @@ var HttpClient = class {
       return true;
     }
   }
+  // ===== cookie 세션 없음 마커 (platform-issue 01a0237f) =====
+  //
+  // `refreshLockedUntil` 백오프는 인스턴스 안에서만 산다. 앱이 클라이언트를 새로 만들 때마다
+  // 초기화되므로, 쿠키가 없는 브라우저에서는 인증 호출마다 re-issue 401 이 새로 나간다.
+  // 이 마커는 같은 사실을 localStorage 에 짧게 남겨 인스턴스 경계를 넘어 공유한다.
+  buildNoCookieSessionKey() {
+    return `${this.storageKey}:no_cookie_session`;
+  }
+  markNoCookieSession() {
+    if (typeof window === "undefined") return;
+    try {
+      localStorage.setItem(this.buildNoCookieSessionKey(), String(Date.now()));
+    } catch {
+    }
+  }
+  clearNoCookieSessionMark() {
+    if (typeof window === "undefined") return;
+    try {
+      localStorage.removeItem(this.buildNoCookieSessionKey());
+    } catch {
+    }
+  }
+  /** 쿠키 전용 refresh 를 지금 건너뛰어야 하는지 (최근에 401/403 을 받았는지). */
+  isNoCookieSessionMarkFresh() {
+    if (typeof window === "undefined") return false;
+    try {
+      const raw = localStorage.getItem(this.buildNoCookieSessionKey());
+      if (!raw) return false;
+      const at = Number.parseInt(raw, 10);
+      if (!Number.isFinite(at)) return false;
+      if (Date.now() - at >= NO_COOKIE_SESSION_COOLDOWN_MS) {
+        this.clearNoCookieSessionMark();
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * OAuth redirect callback 직후 호출되어 HttpOnly cookie 를 부트스트랩한다.
    *
@@ -12101,6 +12758,11 @@ var HttpClient = class {
       this.config.onAuthError?.(error);
       throw error;
     }
+    if (!this.config.refreshToken && this.isNoCookieSessionMarkFresh()) {
+      throw new AuthError(
+        "No cookie session (recently rejected). Skipping token refresh."
+      );
+    }
     this.isRefreshing = true;
     if (!this.config.refreshToken && typeof window === "undefined") {
       this.isRefreshing = false;
@@ -12192,6 +12854,7 @@ var HttpClient = class {
         });
         this.refreshFailureCount = 0;
         this.refreshLockedUntil = 0;
+        this.clearNoCookieSessionMark();
         return data.access_token;
       } catch (e) {
         const baseMsg = e instanceof Error ? e.message : "Token refresh failed";
@@ -12201,6 +12864,9 @@ var HttpClient = class {
           3e4
         );
         this.refreshLockedUntil = Date.now() + backoffMs;
+        if (failureKind === "permanent" && !this.config.refreshToken) {
+          this.markNoCookieSession();
+        }
         if (failureKind === "permanent") {
           if (!silent) {
             this.clearTokens();
@@ -12301,6 +12967,9 @@ var HttpClient = class {
     } else if (!config?.skipAuth && this.config.publicKey && this.config.secretKey && !headers.has("Authorization")) {
       headers.set("Authorization", `Bearer ${this.config.secretKey}`);
     }
+    if (!config?.skipAuth && this.config.secretKey) {
+      headers.set("X-User-Secret-Key", this.config.secretKey);
+    }
     if (config?.headers) {
       Object.entries(config.headers).forEach(([key, value]) => {
         headers.set(key, value);
@@ -13391,6 +14060,7 @@ var ConnectBase = class {
     this.oauth = new OAuthAPI(this.http);
     this.payment = new PaymentAPI(this.http);
     this.subscription = new SubscriptionAPI(this.http);
+    this.organizations = new OrganizationsAPI(this.http);
     this.push = new PushAPI(this.http);
     this.roles = new RolesAPI(this.http);
     this.appMembers = new AppMembersAPI(this.http);
@@ -13502,6 +14172,7 @@ export {
   GameRoom,
   GameRoomTransport,
   NativeAPI,
+  OrganizationsAPI,
   RolesAPI,
   SessionManager,
   VideoProcessingError,