@alneas/appkit-react 0.1.0 → 0.2.0

package/dist/tools/components/auth/adapters/better-auth-adapter.d.ts

@@ -1,115 +1,287 @@
 import { AuthAdapter, User } from '../types.js';
+/**
+ * Host endpoint error payload, or null when no endpoint error is present.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthError = {
+    /** Optional endpoint error text used in adapter Error messages. */
     message?: string;
 } | null;
+/**
+ * Minimal host user fields mapped to Appkit User; remaining keys become metadata.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthUser = {
+    /** Stable host user ID. */
     id: string;
+    /** Optional host email; mapped to an empty string if absent. */
     email?: string;
+    /** Optional host display name. */
     name?: string;
+    /** Optional avatar URL mapped to avatarUrl. */
     image?: string;
+    /** Optional host role copied without authorization checks. */
     role?: string;
 } & Record<string, unknown>;
+/**
+ * Minimal host session fields used for token and organization context lookup.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthSession = {
+    /** Optional session token; nonempty values are used by fallback lookup. */
     token?: string;
+    /** Optional active organization copied into user metadata. */
     activeOrganizationId?: string;
+    /** Optional active team copied into user metadata. */
     activeTeamId?: string;
 } & Record<string, unknown>;
+/**
+ * Nullable host session response; user and session may independently be null.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthSessionData = {
+    /** Host session user, or null for no user. */
     user: BetterAuthUser | null;
+    /** Host session metadata, or null when unavailable. */
     session: BetterAuthSession | null;
 } | null;
+/**
+ * Host response envelope with nullable data and an endpoint error.
+ *
+ * @typeParam T - Successful response payload.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthResponse<T> = {
+    /** Successful payload, or null when unavailable. */
     data: T | null;
+    /** Endpoint failure; null represents no endpoint error. */
     error: BetterAuthError;
 };
+/**
+ * Host token endpoint payload accepted as a string or optional token property.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthTokenData = {
+    /** Nonempty token is preferred; missing/empty values trigger fallback. */
     token?: string;
 } | string;
+/**
+ * Organization mutation response with an optional or envelope endpoint error.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthOrganizationActionResponse = {
+    /** Optional endpoint error; missing or null means no reported error. */
     error?: BetterAuthError;
 } | BetterAuthResponse<unknown>;
+/**
+ * Optional host organization methods; setActive is preferred over setActiveOrganization.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type BetterAuthOrganizationNamespace = {
+    /**
+     * Optional preferred organization switch operation.
+     *
+     * @param params - Organization identifier.
+     *
+     * @returns Host completion response.
+     */
     setActive?: (params: {
+        /** Target organization identifier. */
         organizationId: string;
     }) => Promise<BetterAuthOrganizationActionResponse>;
+    /**
+     * Optional legacy organization switch operation, used only without setActive.
+     *
+     * @param params - Organization identifier.
+     *
+     * @returns Host completion response.
+     */
     setActiveOrganization?: (params: {
+        /** Target organization identifier. */
         organizationId: string;
     }) => Promise<BetterAuthOrganizationActionResponse>;
 };
+/**
+ * Structural host client accepted by BetterAuthAdapter without importing its SDK.
+ *
+ * @remarks Required email sign-in/up, sign-out and session methods may reject with client
+ * errors. Optional account/plugin methods cause the matching adapter operation to reject
+ * when absent, except token which falls back to session lookup.
+ *
+ * @see BetterAuthAdapter for the public host-input example.
+ */
 type MinimalAuthClient = {
+    /**
+     * Email sign-in namespace required by the adapter.
+     */
     signIn: {
+        /**
+         * Submit email credentials through the host client.
+         *
+         * @param params - Account credentials and optional sign-up name.
+         *
+         * @param options - Optional SDK request options; the adapter does not supply them.
+         *
+         * @returns Host response whose user is required for adapter success.
+         */
         email: (params: {
+            /** Account email. */
             email: string;
+            /** Account password. */
             password: string;
         }, options?: Record<string, unknown>) => Promise<BetterAuthResponse<{
+            /** User returned by email sign-in/up; adapter rejects when absent. */
             user?: BetterAuthUser | null;
         }>>;
     };
+    /**
+     * Email sign-up namespace required by the adapter.
+     */
     signUp: {
+        /**
+         * Submit email credentials through the host client.
+         *
+         * @param params - Account credentials and optional sign-up name.
+         *
+         * @param options - Optional SDK request options; the adapter does not supply them.
+         *
+         * @returns Host response whose user is required for adapter success.
+         */
         email: (params: {
+            /** Account email. */
             email: string;
+            /** Account password. */
             password: string;
+            /** Optional display name. */
             name?: string;
         }, options?: Record<string, unknown>) => Promise<BetterAuthResponse<{
+            /** User returned by email sign-in/up; adapter rejects when absent. */
             user?: BetterAuthUser | null;
         }>>;
     };
+    /**
+     * End the host session.
+     *
+     * @returns Endpoint error payload after completion.
+     */
     signOut: () => Promise<{
+        /** Optional endpoint error; missing or null means no reported error. */
         error?: BetterAuthError;
     }>;
+    /**
+     * Read the host session.
+     *
+     * @returns Nullable user/session payload and endpoint error.
+     */
     getSession: () => Promise<BetterAuthResponse<BetterAuthSessionData>>;
+    /**
+     * Optional JWT/token endpoint; adapter swallows endpoint failures before session fallback.
+     *
+     * @returns Token payload and endpoint error.
+     */
     token?: () => Promise<BetterAuthResponse<BetterAuthTokenData>>;
+    /**
+     * Optional password-reset endpoint.
+     *
+     * @param params - Account email and optional redirect destination.
+     *
+     * @returns Completion response with optional endpoint error.
+     */
     forgetPassword?: (params: {
+        /** Optional host email; mapped to an empty string if absent. */
         email: string;
+        /** Optional reset redirect; adapter supplies /reset-password. */
         redirectTo?: string;
     }) => Promise<{
+        /** Optional endpoint error; missing or null means no reported error. */
         error?: BetterAuthError;
     }>;
+    /**
+     * Optional password-change endpoint.
+     *
+     * @param params - New password and optional host-only verification/session switches.
+     *
+     * @returns Completion response with optional endpoint error.
+     */
     changePassword?: (params: {
+        /** Replacement password sent by the adapter. */
         newPassword: string;
+        /** Optional current password supported by the host; adapter does not supply it. */
         currentPassword?: string;
+        /** Optional host session-revocation switch; adapter does not supply it. */
         revokeOtherSessions?: boolean;
     }) => Promise<{
+        /** Optional endpoint error; missing or null means no reported error. */
         error?: BetterAuthError;
     }>;
+    /**
+     * Optional email-change endpoint.
+     *
+     * @param params - New email address.
+     *
+     * @returns Completion response with optional endpoint error.
+     */
     changeEmail?: (params: {
+        /** Replacement account email. */
         newEmail: string;
     }) => Promise<{
+        /** Optional endpoint error; missing or null means no reported error. */
         error?: BetterAuthError;
     }>;
+    /** Optional organization plugin namespace. */
     organization?: BetterAuthOrganizationNamespace;
 };
+/**
+ * Polling and browser event settings; see BetterAuthAdapter for host setup.
+ * @see BetterAuthAdapter for the canonical usage example.
+ */
 export interface BetterAuthAdapterOptions {
     /**
-     * onAuthStateChanged で監視するカスタムイベント名
-     * @default "better-auth:session-changed"
+     * Custom window event observed by onAuthStateChanged.
+     *
+     * @defaultValue "better-auth:session-changed"
      */
     sessionChangeEventName?: string;
     /**
-     * セッションポーリング間隔(ms)。0以下で無効化
-     * @default 30000
+     * Session polling interval in milliseconds; zero or negative disables polling.
+     *
+     * @defaultValue 30000
      */
     pollIntervalMs?: number;
 }
 /**
- * Better Auth 用のアダプタークラス
+ * Adapts a host-supplied Better Auth client to Appkit authentication operations.
  *
- * Better Auth クライアントをラップし、アプリケーション共通の AuthAdapter インターフェースを提供します。
- * これにより、UIコンポーネントは認証プロバイダーの実装詳細を気にすることなく利用できます。
- * Better Auth SDKはこのパッケージの依存ではありません。利用アプリでSDKを導入し、
- * 必要なメソッドを持つクライアントを渡してください。
+ * @remarks The host installs/configures the Better Auth SDK and server and supplies a
+ * structurally compatible client. No SDK or working backend is created by this class.
+ * Subscriptions use an initial session read, custom window events and optional polling;
+ * each returned cleanup stops its listener/timer. AuthProvider requires an outer
+ * QueryClientProvider; this adapter alone requires neither CSS nor a React provider.
  *
  * @example
  * ```tsx
- * import { createAuthClient } from 'better-auth/react'; // installed by the consuming application
- * const authClient = createAuthClient();
- * import { BetterAuthAdapter, AuthProvider } from "@alneas/appkit-react/tools/auth";
- *
- * const adapter = new BetterAuthAdapter(authClient);
- *
- * <AuthProvider adapter={adapter}>
- *   <App />
- * </AuthProvider>
+ * import type { ReactNode } from 'react';
+ * import { useMemo } from 'react';
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { BetterAuthAdapter, AuthProvider } from '@alneas/appkit-react/tools/auth';
+ * export function BetterAuthRoot({ authClient, queryClient, children }: {
+ *   authClient: ConstructorParameters<typeof BetterAuthAdapter>[0];
+ *   queryClient: QueryClient;
+ *   children: ReactNode;
+ * }) {
+ *   const adapter = useMemo(() => new BetterAuthAdapter(authClient), [authClient]);
+ *   return <QueryClientProvider client={queryClient}>
+ *     <AuthProvider adapter={adapter}>{children}</AuthProvider>
+ *   </QueryClientProvider>;
+ * }
  * ```
  */
 export declare class BetterAuthAdapter implements AuthAdapter {
@@ -118,84 +290,232 @@ export declare class BetterAuthAdapter implements AuthAdapter {
     private pollIntervalMs;
     private inFlightSession;
     /**
-     * @param client Better Auth クライアントインスタンス (createAuthClient で作成されたもの)
+     * Creates an adapter around an already configured host client.
+     *
+     * @param client - Compatible Better Auth client with email sign-in/up, sign-out and getSession.
+     *
+     * @param options - Event name and polling interval; defaults to better-auth:session-changed and 30000 ms.
+     *
+     * @remarks Construction makes no requests and starts no listeners; see the class example.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export function adapt(client: ConstructorParameters<typeof BetterAuthAdapter>[0]) {
+     *   return new BetterAuthAdapter(client, { pollIntervalMs: 0 });
+     * }
+     * ```
      */
     constructor(client: MinimalAuthClient, options?: BetterAuthAdapterOptions);
     /**
-     * メールアドレスとパスワードでログインします。
+     * Signs in with the client email/password endpoint.
+     *
+     * @param email - User email address.
+     *
+     * @param password - User password.
      *
-     * @param email ユーザーのメールアドレス
-     * @param password パスワード
-     * @returns ログインしたユーザー情報
-     * @throws ログインに失敗した場合にエラーを投げます
+     * @returns The mapped signed-in user; emits the session-change event on success.
+     *
+     * @throws Rejects on client failure, endpoint error or a response missing a user.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.login('person@example.com', password);
+     * }
+     * ```
      */
     login(email: string, password: string): Promise<User>;
     /**
-     * 新規ユーザー登録を行います。
+     * Creates an account through the client email sign-up endpoint.
+     *
+     * @param email - New account email.
      *
-     * @param email メールアドレス
-     * @param password パスワード
-     * @param data 追加データ (現在は name のみサポート)
-     * @returns 登録されたユーザー情報
-     * @throws 登録に失敗した場合にエラーを投げます
+     * @param password - New account password.
+     *
+     * @param data - Optional name; omitted or empty names are sent as an empty string.
+     *
+     * @returns The mapped registered user; emits the session-change event on success.
+     *
+     * @throws Rejects on client failure, endpoint error or a response missing a user.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.register('person@example.com', password, { name: 'Reader' });
+     * }
+     * ```
      */
     register(email: string, password: string, data?: {
+        /** Optional display name forwarded as an empty string when omitted. */
         name?: string;
     }): Promise<User>;
     /**
-     * ログアウトします。
+     * Signs out through the supplied client.
+     *
+     *
+     * @returns No value after sign-out succeeds and the session-change event is emitted.
+     *
+     * @throws Rejects on client failure or endpoint error.
      *
-     * @returns 完了時の Promise
-     * @throws ログアウトに失敗した場合にエラーを投げます
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.logout();
+     * }
+     * ```
      */
     logout(): Promise<void>;
     /**
-     * 現在のユーザーを取得します。
-     * Better Auth の getSession メソッドを使用してセッション情報を取得します。
+     * Reads the current user, coalescing concurrent reads on this adapter.
+     *
+     *
+     * @returns The mapped session user, or null for no session, endpoint errors or thrown read failures.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.getCurrentUser();
+     * }
+     * ```
      */
     getCurrentUser(): Promise<User | null>;
     /**
-     * SupabaseTokenProvider 用に認証トークンを取得します。
+     * Reads a token, trying the optional token endpoint before the session token.
+     *
      *
-     * 優先順位:
-     * 1. Better Auth JWT plugin の `/token` エンドポイント
-     * 2. セッションの `session.token`
+     * @returns A nonempty token string or null if no token is available.
+     *
+     * @throws Rejects if the fallback session request throws; token-endpoint failures are swallowed.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.getToken();
+     * }
+     * ```
      */
     getToken(): Promise<string | null>;
     /**
-     * organization plugin が有効な場合、アクティブな組織を切り替えます。
+     * Changes the active organization using the optional organization client namespace.
+     *
+     * @param organizationId - Organization identifier sent to setActive or setActiveOrganization.
+     *
+     * @returns No value after success; emits a session-change event.
+     *
+     * @throws Rejects if the plugin method is missing, the client rejects or an endpoint error is returned.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.setActiveOrganization('selected-organization');
+     * }
+     * ```
      */
     setActiveOrganization(organizationId: string): Promise<void>;
     /**
-     * 現在の organization / team コンテキストを取得します。
+     * Reads active organization/team identifiers from the current session.
+     *
+     *
+     * @returns An object whose two identifiers are strings when present and null otherwise.
+     *
+     * @throws Rejects if the session request throws; returned endpoint errors produce null identifiers.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.getOrganizationContext();
+     * }
+     * ```
      */
     getOrganizationContext(): Promise<{
+        /** Active organization, or null when absent. */
         activeOrganizationId: string | null;
+        /** Active team, or null when absent. */
         activeTeamId: string | null;
     }>;
     /**
-     * 認証状態の変更を監視します。
+     * Observes session state using an initial read, browser events and optional polling.
      *
-     * Better Auth は内部的に nanostore (atom) を使用して状態管理を行いますが、
-     * window イベントは発火しません。このメソッドは以下の方法で状態変化を検出します：
+     * @param callback - Receives the mapped user or null after each read; callbacks can repeat unchanged values.
      *
-     * 1. 初回呼び出し時に現在のユーザーを取得
-     * 2. カスタムウィンドウイベントをリッスン (デフォルト: 'better-auth:session-changed')
-     * 3. 定期的なポーリング（フォールバック）
+     * @returns Cleanup that disables the initial callback and removes browser listeners/timers.
      *
-     * @deprecated React コンポーネント内では useAuth() の使用を推奨します。
+     * @remarks On the server only the initial asynchronous read occurs. Browser polling defaults
+     * to 30000 ms and is disabled by nonpositive intervals. Callback errors are not caught.
+     * An already-running event/poll read may still invoke callback after cleanup.
+     *
+     * @deprecated React consumers should use useAuth under AuthProvider for managed lifecycle/state.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter, type User } from '@alneas/appkit-react/tools/auth';
+     * export function observe(adapter: BetterAuthAdapter, onUser: (user: User | null) => void) {
+     *   return adapter.onAuthStateChanged(onUser);
+     * }
+     * // The host calls the returned cleanup when observation ends.
+     * ```
      */
     onAuthStateChanged(callback: (user: User | null) => void): () => void;
     /**
-     * メールアドレスを更新します。
+     * Requests an email change through the optional changeEmail endpoint.
+     *
+     * @param email - New email address.
+     *
+     * @returns No value after the endpoint succeeds; this method emits no session-change event.
+     *
+     * @throws Rejects if changeEmail is absent, the client rejects or an endpoint error is returned.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.updateEmail('new@example.com');
+     * }
+     * ```
      */
     updateEmail(email: string): Promise<void>;
     /**
-     * パスワードを更新します。
+     * Requests a password change through the optional changePassword endpoint.
+     *
+     * @param password - New password; this method does not send a current password.
+     *
+     * @returns No value after the endpoint succeeds; this method emits no session-change event.
+     *
+     * @throws Rejects if changePassword is absent, the client rejects or an endpoint error is returned.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.updatePassword(password);
+     * }
+     * ```
      */
     updatePassword(password: string): Promise<void>;
     /**
-     * パスワードリセットメールを送信します。
+     * Requests a password-reset email with redirectTo set to /reset-password.
+     *
+     * @param email - Account email address.
+     *
+     * @returns No value after the endpoint succeeds; delivery is owned by the host backend.
+     *
+     * @throws Rejects if forgetPassword is absent, the client rejects or an endpoint error is returned.
+     *
+     * @example
+     * ```ts
+     * import { BetterAuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function run(adapter: BetterAuthAdapter, password: string) {
+     *   return adapter.resetPassword('person@example.com');
+     * }
+     * ```
      */
     resetPassword(email: string): Promise<void>;
     private getSessionData;