/** 应用自己的终端用户（与 ChatU 平台账号无关） */
export interface AppUser {
    id: string;
    /** 应用自建用户一定有；渠道账号模式下取决于渠道资料，可能为空 */
    email: string | null;
    name: string | null;
    avatar: string | null;
    createdAt: number;
    lastLoginAt: number;
    disabled: boolean;
    meta: Record<string, unknown>;
    /** 渠道账号模式下的渠道账号名（裸账号，不含前缀）；三方登录为提供方登录名（GitHub login；微信没有）；应用自建用户没有此字段 */
    username?: string;
    /** 用户来源：应用自建（缺省）、渠道账号，或三方登录提供方（wechat / wechat-mp / github …） */
    source?: 'channel' | OAuthProvider;
}
export interface SignInResult {
    token: string;
    user: AppUser;
    created: boolean;
}
export interface SendCodeResult {
    sent: boolean; /** 仅预览环境且平台未配置邮件通道时返回，便于调试 */
    devCode?: string | null;
}
export interface UserListResult {
    users: AppUser[];
    total: number;
    nextSkip: number | null;
}
export interface UserPatch {
    name?: string | null;
    avatar?: string | null;
    disabled?: boolean;
    meta?: Record<string, unknown>;
    password?: string;
}
/** 角色读写（技术方案 34 §3）：存 user.meta.roles，ADMIN_EMAILS 里的邮箱隐式 admin */
export interface AuthRoles {
    /** 这个用户的角色列表（含 ADMIN_EMAILS 带来的 admin）；未登录返回空数组 */
    of(user: AppUser | null | undefined): string[];
    /** 是否具备其中任一角色 */
    has(user: AppUser | null | undefined, ...roles: string[]): boolean;
    /** 给用户加角色（读 meta → 合并 → 整体写回），返回更新后的用户 */
    grant(userId: string, ...roles: string[]): Promise<AppUser>;
    /** 去掉角色（ADMIN_EMAILS 带来的 admin 去不掉，要改环境变量） */
    revoke(userId: string, ...roles: string[]): Promise<AppUser>;
}
/** 三方登录提供方：wechat（开放平台扫码，PC）、wechat-mp（公众号 H5，微信内）、github */
export type OAuthProvider = 'wechat' | 'wechat-mp' | 'github' | 'gitee' | 'qq' | (string & {});
export interface OAuthStartOptions {
    /** 应用自己的回调路由**绝对地址**（如 `${origin}/api/auth/oauth/callback`）；平台登录完成后带 ?ticket= 回到这里 */
    callbackUrl: string;
    /** 登录完成后应用内要回到的路径（只允许站内相对路径，如 /dashboard） */
    returnTo?: string;
    /** redirect（整页跳转，缺省）| popup（弹窗内完成，回调页 postMessage 给 opener；预览 iframe 里必须用这个） */
    mode?: 'redirect' | 'popup';
}
export interface OAuthStartResult {
    url: string;
}
export interface OAuthProviderStatus {
    provider: OAuthProvider;
    configured: boolean; /** 缺少的环境变量名 */
    missing: string[];
}
export interface OAuthProvidersResult {
    providers: OAuthProviderStatus[];
    /** 平台回调域（微信后台「授权回调域 / 网页授权域名」填这个） */
    callbackDomain: string | null;
    /** 平台回调完整地址（GitHub OAuth App 的 Authorization callback URL 填这个） */
    callbackUrl: string | null;
}
export interface AuthClient {
    /** 发送邮箱登录验证码 */
    sendCode(email: string): Promise<SendCodeResult>;
    /** 校验验证码；邮箱首次登录自动注册 */
    verifyCode(email: string, code: string, opts?: {
        name?: string;
    }): Promise<SignInResult>;
    /** 邮箱 + 密码注册 */
    register(email: string, password: string, opts?: {
        name?: string;
    }): Promise<SignInResult>;
    /**
     * 密码登录。
     * - app 模式（默认）：第一个参数是邮箱；
     * - channel 模式：第一个参数是**渠道裸账号**（与登录渠道站点时输入的一致，不带前缀）。
     */
    login(account: string, password: string): Promise<SignInResult>;
    /** 用会话 token 换当前用户；无效/过期/被禁用返回 null */
    getSession(token: string | null | undefined): Promise<AppUser | null>;
    /** 退出登录（吊销该 token） */
    signOut(token: string | null | undefined): Promise<boolean>;
    users: {
        list(opts?: {
            skip?: number;
            limit?: number;
            keyword?: string;
        }): Promise<UserListResult>;
        get(id: string): Promise<AppUser | null>;
        update(id: string, patch: UserPatch): Promise<AppUser>;
        delete(id: string): Promise<boolean>;
    };
    /**
     * 角色（技术方案 34 §3）：角色存在 `user.meta.roles` 里，另外 `ADMIN_EMAILS` 环境变量里的邮箱**隐式拥有 admin**
     * （第一个管理员就是这么来的，不需要先有人给他授权）。
     */
    roles: AuthRoles;
    /** 要求用户具备其中任一角色，否则抛 AppSdkError('FORBIDDEN', …, 403)；返回原用户方便串写 */
    requireRole(user: AppUser | null | undefined, ...roles: string[]): AppUser;
    /**
     * 三方登录（微信扫码 / 公众号 H5 / GitHub）。三步都在**应用服务端**调用：
     * 1. start(provider, { callbackUrl }) 取授权页地址 → 302 过去（或弹窗打开）；
     * 2. 用户在提供方授权后，平台回调把一次性 ticket 带回 callbackUrl；
     * 3. exchange(ticket) 换会话 token（60 秒内有效、只能用一次），之后与其他登录方式一样写 cookie。
     * 提供方的 AppID/Secret 由用户在「环境变量」里配置（WECHAT_APP_ID… / GITHUB_CLIENT_ID…），
     * 未配置时 start() 抛 OAUTH_NOT_CONFIGURED，details.missing 列出缺的变量名。
     */
    oauth: {
        start(provider: OAuthProvider, opts: OAuthStartOptions): Promise<OAuthStartResult>;
        exchange(ticket: string): Promise<SignInResult>;
        /** 各提供方是否已配置（登录页据此决定显示哪些按钮）+ 平台回调域/地址 */
        providers(): Promise<OAuthProvidersResult>;
    };
}
/** 按当前配置取 auth 客户端（惰性、缓存；configure() 后自动重建） */
export declare function getAuth(): AuthClient;
/** 便捷单例：`import { auth } from '@chatu-ai/app-sdk'` */
export declare const auth: AuthClient;