@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/identity/factory/user-factory.d.ts

@@ -2,6 +2,9 @@ import { User } from '../entity/user';
 import { ServerConfig } from '../value-object/server-config';
 import { Device } from '../value-object/device';
 import { HttpClient, IdentityStorageProvider } from '../repository/index';
+/**
+ * Trial License Response
+ */
 export interface TrialLicenseResponse {
     email: string;
     license_key: string;
@@ -10,6 +13,9 @@ export interface TrialLicenseResponse {
     success: boolean;
     validity_days: number;
 }
+/**
+ * License Activation Response
+ */
 export interface LicenseActivationResponse {
     activated: boolean;
     first_time: boolean;
@@ -41,6 +47,9 @@ export interface LicenseActivationResponse {
         status: string;
     };
 }
+/**
+ * Domain Info Response
+ */
 export interface DomainInfo {
     subdomain: string;
     full_domain: string;
@@ -48,61 +57,232 @@ export interface DomainInfo {
     folder: string;
     created_at: number;
 }
+/**
+ * Subdomain Check Response
+ */
 export interface SubdomainCheckResponse {
     available: boolean;
     message?: string;
 }
+/**
+ * Subdomain Update Response
+ */
 export interface SubdomainUpdateResponse {
     new_subdomain: string;
     old_subdomain: string;
     full_domain: string;
     message: string;
 }
+/**
+ * UserFactory Options
+ */
 export interface UserFactoryOptions {
     httpClient: HttpClient;
     storageProvider: IdentityStorageProvider;
 }
+/**
+ * UserFactory
+ *
+ * 负责创建和加载 User 聚合根
+ *
+ * 职责：
+ * - 创建新用户（注册）
+ * - 加载现有用户（从存储）
+ * - 用户登录
+ * - 用户登出
+ * - 管理用户持久化
+ */
 export declare class UserFactory {
     private httpClient;
     private storageProvider;
     constructor(options: UserFactoryOptions);
+    /**
+     * 创建匿名用户（未登录状态）
+     */
     createAnonymous(serverConfig?: ServerConfig): User;
+    /**
+     * 从存储加载用户
+     */
     load(): Promise<User | null>;
+    /**
+     * 保存用户到存储（合并保存 token, license, server config, sync config）
+     *
+     * ⚠️ 采用合并策略：先加载现有数据，再用新数据覆盖，避免丢失其他字段
+     */
     save(user: User): Promise<void>;
+    /**
+     * 加载已保存的服务器配置
+     */
     loadServerConfig(): Promise<ServerConfig | null>;
+    /**
+     * 用户登录
+     *
+     * @param email - 用户邮箱
+     * @param password - 用户密码
+     * @param serverConfig - 可选的服务器配置
+     * @returns 登录成功的 User 实例
+     */
     login(email: string, password: string, serverConfig?: ServerConfig): Promise<User>;
+    /**
+     * 用户注册
+     *
+     * @param email - 用户邮箱
+     * @param password - 用户密码
+     * @param serverConfig - 可选的服务器配置
+     * @returns 注册成功的 User 实例
+     */
     register(email: string, password: string, serverConfig?: ServerConfig): Promise<User>;
+    /**
+     * 用户登出
+     */
     logout(): Promise<void>;
+    /**
+     * 更新服务器配置
+     */
     updateServerConfig(user: User, updates: {
         apiUrl?: string;
         websiteUrl?: string;
     }): Promise<void>;
+    /**
+     * 申请试用 License
+     *
+     * @param email - 用户邮箱
+     * @param serverConfig - 可选的服务器配置
+     * @returns 试用 License 信息和自动生成的凭证
+     */
     requestTrialLicense(email: string, serverConfig?: ServerConfig): Promise<TrialLicenseResponse>;
+    /**
+     * 使用 License Key 登录
+     *
+     * License Key 可以自动生成 email 和 password
+     * 登录成功后会保存 License Key，用户可以后续使用
+     *
+     * @param licenseKey - License Key (MDF-XXXX-XXXX-XXXX)
+     * @param serverConfig - 可选的服务器配置
+     * @returns 登录成功的 User 实例
+     */
     loginWithLicense(licenseKey: string, serverConfig?: ServerConfig): Promise<User>;
+    /**
+     * 激活 License
+     *
+     * @param user - 已登录的用户
+     * @param licenseKey - License Key
+     * @param device - 设备信息（可选，不提供则自动生成）
+     * @returns 更新后的 User（包含激活的 License）
+     */
     activateLicense(user: User, licenseKey: string, device?: Device): Promise<User>;
+    /**
+     * 完整的试用流程：申请 → 登录 → 激活
+     *
+     * 简化用户操作：只需提供邮箱，自动完成所有步骤
+     *
+     * @param email - 用户邮箱
+     * @param serverConfig - 可选的服务器配置
+     * @returns 已激活 License 的 User
+     */
     requestAndActivateTrial(email: string, serverConfig?: ServerConfig): Promise<User>;
+    /**
+     * 自动刷新 Token（如果需要）
+     *
+     * 当用户使用 License 登录后，token 会在 30 天后过期
+     * 此方法检查 token 是否即将过期或已过期，如果是则自动使用 license 重新登录
+     *
+     * @param user - 当前用户
+     * @returns 更新后的用户（如果刷新了 token）或原用户
+     */
     refreshTokenIfNeeded(user: User): Promise<User>;
+    /**
+     * 执行需要认证的请求，自动处理 token 刷新
+     *
+     * 这是一个包装方法，模仿 @friday/src/hugoverse.ts 的 requestWithTokenRefresh
+     * 当请求返回 401 时，自动刷新 token 并重试
+     *
+     * @param user - 当前用户
+     * @param requestFn - 执行实际请求的函数，接收 token 字符串作为参数
+     * @returns 请求结果
+     */
     requestWithAutoRefresh<T>(user: User, requestFn: (tokenValue: string) => Promise<T>): Promise<T>;
+    /**
+     * 获取 License 使用量信息
+     *
+     * @param user - 当前用户
+     * @returns License 使用量信息
+     */
     getLicenseUsage(user: User): Promise<LicenseUsageResponse | null>;
+    /**
+     * 获取 License 详细信息
+     *
+     * @param user - 当前用户
+     * @param licenseKey - 可选的 License Key，如果不提供则从 user 的 license 中获取
+     * @returns License 详细信息
+     */
     getLicenseInfo(user: User, licenseKey?: string): Promise<any>;
+    /**
+     * 重置 License 使用量
+     * 清除同步数据库和发布数据
+     *
+     * @param user - 当前用户
+     * @returns 重置结果
+     */
     resetUsage(user: User): Promise<{
         success: boolean;
         message?: string;
     }>;
+    /**
+     * 获取域名信息
+     *
+     * @param user - 当前用户
+     * @returns 域名信息（包括子域名和自定义域名）
+     */
     getDomains(user: User): Promise<DomainInfo | null>;
+    /**
+     * 检查子域名可用性
+     *
+     * @param user - 当前用户
+     * @param subdomain - 要检查的子域名
+     * @returns 可用性检查结果
+     */
     checkSubdomainAvailability(user: User, subdomain: string): Promise<SubdomainCheckResponse | null>;
+    /**
+     * 更新子域名
+     *
+     * @param user - 当前用户
+     * @param newSubdomain - 新的子域名
+     * @returns 更新结果
+     */
     updateSubdomain(user: User, newSubdomain: string): Promise<SubdomainUpdateResponse | null>;
+    /**
+     * 检查自定义域名 DNS 配置
+     *
+     * @param user - 当前用户
+     * @param domain - 要检查的域名
+     * @returns DNS 检查结果
+     */
     checkCustomDomain(user: User, domain: string): Promise<{
         dns_valid: boolean;
         ready: boolean;
         message: string;
         resolved_ips?: string[];
     } | null>;
+    /**
+     * 添加自定义域名
+     *
+     * @param user - 当前用户
+     * @param domain - 要添加的域名
+     * @returns 添加结果
+     */
     addCustomDomain(user: User, domain: string): Promise<{
         domain: string;
         status: string;
         message: string;
     } | null>;
+    /**
+     * 检查自定义域名 HTTPS 证书状态
+     *
+     * @param user - 当前用户
+     * @param domain - 要检查的域名
+     * @returns HTTPS 状态
+     */
     checkCustomDomainHttpsStatus(user: User, domain: string): Promise<{
         status: string;
         tls_ready: boolean;
@@ -111,6 +291,9 @@ export declare class UserFactory {
         certificate?: any;
     } | null>;
 }
+/**
+ * License Usage Response (from API)
+ */
 export interface LicenseUsageResponse {
     devices: {
         count: number;

package/dist/types/internal/domain/identity/repository/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Identity Repository Interfaces
+ *
+ * 定义 Identity Domain 需要的存储接口
+ * 由 Infrastructure 层或其他 Domain 提供实现
+ */
+/**
+ * HTTP Client 接口
+ * 用于发送 HTTP 请求（登录、注册等）
+ */
 export interface HttpClient {
     post(url: string, data: any, headers?: Record<string, string>): Promise<HttpResponse>;
     postForm(url: string, data: Record<string, string>): Promise<HttpResponse>;
@@ -9,7 +19,21 @@ export interface HttpResponse {
     data: any;
     text(): Promise<string>;
 }
+/**
+ * Identity Storage Provider 接口
+ *
+ * 定义 Identity Domain 需要的存储能力
+ * 实现由 Workspace Domain 提供（通过 Application Layer 协调）
+ *
+ * 这是依赖倒置的关键：
+ * - Identity Domain 定义自己需要什么存储能力
+ * - Workspace Domain 实现这些能力
+ * - Application Layer 负责组装
+ */
 export interface IdentityStorageProvider {
+    /**
+     * 保存用户数据（合并 token, license, server config, sync config 到一个文件）
+     */
     saveUserData(data: {
         token?: any;
         license?: any;
@@ -17,6 +41,9 @@ export interface IdentityStorageProvider {
         serverConfig?: any;
         email?: string;
     }): Promise<void>;
+    /**
+     * 加载用户数据
+     */
     loadUserData(): Promise<{
         token?: any;
         license?: any;
@@ -24,5 +51,8 @@ export interface IdentityStorageProvider {
         serverConfig?: any;
         email?: string;
     } | null>;
+    /**
+     * 清除用户数据
+     */
     clearUserData(): Promise<void>;
 }

package/dist/types/internal/domain/identity/type.d.ts

@@ -1,17 +1,34 @@
+/**
+ * Identity Domain Types
+ *
+ * 这些是简单的数据传输对象 (DTOs)，不是 Domain 对象
+ */
+/**
+ * User credentials (用于登录/注册)
+ */
 export interface UserCredentials {
     email: string;
     password: string;
 }
+/**
+ * User profile (用户资料)
+ */
 export interface UserProfile {
     email: string;
     name?: string;
     avatar?: string;
 }
+/**
+ * Login response (登录响应)
+ */
 export interface LoginResponse {
     token: string;
     expiresAt?: number;
     user?: UserProfile;
 }
+/**
+ * Register response (注册响应)
+ */
 export interface RegisterResponse {
     token: string;
     expiresAt?: number;

package/dist/types/internal/domain/identity/value-object/device.d.ts

@@ -1,13 +1,39 @@
+/**
+ * Device Value Object
+ *
+ * 不可变的设备值对象
+ * 用于 License 激活时的设备识别
+ */
 export type DeviceType = 'desktop' | 'mobile' | 'tablet';
 export declare class Device {
     private readonly id;
     private readonly name;
     private readonly type;
     private constructor();
+    /**
+     * 创建 Device 实例
+     */
     static create(id: string, name: string, type: DeviceType): Device;
+    /**
+     * 从当前环境创建 Device
+     * 使用浏览器特征生成稳定的设备指纹
+     */
     static createFromEnvironment(): Promise<Device>;
+    /**
+     * 生成稳定的设备指纹
+     * 使用浏览器/系统特征，在会话间保持稳定
+     * 适配 Node.js 和 Browser/Electron 环境
+     */
     private static generateFingerprint;
+    /**
+     * 获取设备名称
+     * 适配 Node.js 和 Browser/Electron 环境
+     */
     private static getDeviceName;
+    /**
+     * 获取设备类型
+     * 适配 Node.js 和 Browser/Electron 环境
+     */
     private static getDeviceType;
     getId(): string;
     getName(): string;

package/dist/types/internal/domain/identity/value-object/email.d.ts

@@ -1,12 +1,41 @@
+/**
+ * Email Value Object
+ *
+ * 不可变的电子邮件地址值对象
+ */
 export declare class Email {
     private readonly value;
     private constructor();
+    /**
+     * 创建 Email 实例
+     */
     static create(email: string): Email;
+    /**
+     * 验证邮箱格式
+     */
     static isValid(email: string): boolean;
+    /**
+     * 获取邮箱字符串
+     */
     getValue(): string;
+    /**
+     * 获取邮箱域名
+     */
     getDomain(): string;
+    /**
+     * 获取用户名部分
+     */
     getLocalPart(): string;
+    /**
+     * 比较两个 Email 是否相等
+     */
     equals(other: Email): boolean;
+    /**
+     * 转换为字符串
+     */
     toString(): string;
+    /**
+     * 序列化为 JSON
+     */
     toJSON(): string;
 }

package/dist/types/internal/domain/identity/value-object/license.d.ts

@@ -1,3 +1,16 @@
+/**
+ * License Value Object
+ *
+ * 不可变的许可证值对象
+ *
+ * License Key format: MDF-XXXX-XXXX-XXXX
+ * - License key 可以直接生成 email 和 password
+ * - email = [key-without-prefix]@mdfriday.com
+ * - password = base64(key-without-prefix)
+ */
+/**
+ * License Features
+ */
 export interface LicenseFeatures {
     maxDevices: number;
     maxIps: number;
@@ -10,6 +23,9 @@ export interface LicenseFeatures {
     customSubDomain: boolean;
     validityDays: number;
 }
+/**
+ * License Plan Type
+ */
 export type LicensePlan = 'free' | 'starter' | 'enjoy' | 'creator' | 'pro' | 'enterprise';
 export declare class License {
     private readonly key;
@@ -20,7 +36,13 @@ export declare class License {
     private readonly activated;
     private readonly firstTime;
     private constructor();
+    /**
+     * 创建 License 实例
+     */
     static create(key: string, plan: LicensePlan, expiresAt: number, features: LicenseFeatures, activatedAt?: number, activated?: boolean, firstTime?: boolean): License;
+    /**
+     * 从 JSON 数据创建 License
+     */
     static fromJSON(data: {
         key: string;
         plan: LicensePlan;
@@ -30,25 +52,91 @@ export declare class License {
         activated?: boolean;
         firstTime?: boolean;
     }): License;
+    /**
+     * 验证 License Key 格式
+     * Expected format: MDF-XXXX-XXXX-XXXX (alphanumeric)
+     */
     static isValidFormat(key: string): boolean;
+    /**
+     * 检查 License 是否已过期
+     */
     isExpired(): boolean;
+    /**
+     * 检查 License 是否有效（未过期）
+     */
     isValid(): boolean;
+    /**
+     * 获取剩余天数
+     */
     getDaysRemaining(): number;
+    /**
+     * 从 License Key 生成 Email
+     * Format: [key-without-prefix]@mdfriday.com
+     * Example: MDF-ABC1-DEF2-GHI3 → abc1-def2-ghi3@mdfriday.com
+     */
     getEmail(): string;
+    /**
+     * 从 License Key 生成 Password
+     * Uses base64 encoding of the key portion (without MDF- prefix)
+     * 适配 Browser 和 Node.js 环境
+     */
     getPassword(): string;
+    /**
+     * Manual base64 encoding fallback
+     */
     private manualBase64Encode;
+    /**
+     * 获取 License Key（原始格式）
+     */
     getKey(): string;
+    /**
+     * 获取掩码后的 License Key
+     * Shows: MDF-••••-••••-XXXX
+     */
     getMaskedKey(): string;
+    /**
+     * 获取 Plan
+     */
     getPlan(): LicensePlan;
+    /**
+     * 获取格式化的 Plan 名称
+     */
     getFormattedPlan(): string;
+    /**
+     * 获取过期时间戳
+     */
     getExpiresAt(): number;
+    /**
+     * 获取格式化的过期日期
+     */
     getFormattedExpiresAt(): string;
+    /**
+     * 获取 Features
+     */
     getFeatures(): LicenseFeatures;
+    /**
+     * 获取激活时间
+     */
     getActivatedAt(): number;
+    /**
+     * 获取激活状态
+     */
     isActivated(): boolean;
+    /**
+     * 是否首次激活
+     */
     isFirstTime(): boolean;
+    /**
+     * 检查是否是试用 License
+     */
     isTrial(): boolean;
+    /**
+     * 比较两个 License 是否相同
+     */
     equals(other: License): boolean;
+    /**
+     * 序列化为 JSON
+     */
     toJSON(): {
         key: string;
         plan: LicensePlan;
@@ -58,6 +146,9 @@ export declare class License {
         activated: boolean;
         firstTime: boolean;
     };
+    /**
+     * 转换为存储格式（包含掩码）
+     */
     toStorageFormat(): {
         key: string;
         maskedKey: string;

package/dist/types/internal/domain/identity/value-object/server-config.d.ts

@@ -1,19 +1,56 @@
+/**
+ * ServerConfig Value Object
+ *
+ * 不可变的服务器配置值对象
+ */
 export declare class ServerConfig {
     private readonly apiUrl;
     private readonly websiteUrl;
     private constructor();
+    /**
+     * 创建 ServerConfig 实例
+     */
     static create(apiUrl: string, websiteUrl?: string): ServerConfig;
+    /**
+     * 从 JSON 数据创建 ServerConfig
+     */
     static fromJSON(data: {
         apiUrl: string;
         websiteUrl?: string;
     }): ServerConfig;
+    /**
+     * 创建默认配置
+     *
+     * 用户可以通过 mdf auth:config 命令修改服务器 URL
+     */
     static createDefault(): ServerConfig;
+    /**
+     * 验证 URL 格式
+     */
     private static isValidUrl;
+    /**
+     * 获取 API URL
+     */
     getApiUrl(): string;
+    /**
+     * 获取网站 URL
+     */
     getWebsiteUrl(): string | undefined;
+    /**
+     * 更新 API URL（返回新实例）
+     */
     withApiUrl(apiUrl: string): ServerConfig;
+    /**
+     * 更新网站 URL（返回新实例）
+     */
     withWebsiteUrl(websiteUrl?: string): ServerConfig;
+    /**
+     * 比较两个 ServerConfig 是否相等
+     */
     equals(other: ServerConfig): boolean;
+    /**
+     * 序列化为 JSON
+     */
     toJSON(): {
         apiUrl: string;
         websiteUrl?: string;

package/dist/types/internal/domain/identity/value-object/sync-config.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Sync Configuration Value Object
+ *
+ * 同步配置值对象，用于存储 CouchDB 同步配置信息
+ * 此配置从 License 激活时由后端返回
+ */
 export interface SyncConfigData {
     dbEndpoint: string;
     dbName: string;
@@ -14,17 +20,55 @@ export declare class SyncConfig {
     private readonly userDir;
     private readonly status;
     private constructor();
+    /**
+     * 创建 SyncConfig 实例
+     */
     static create(data: SyncConfigData): SyncConfig;
+    /**
+     * 从 JSON 数据创建 SyncConfig
+     */
     static fromJSON(data: SyncConfigData): SyncConfig;
+    /**
+     * 获取数据库端点 URL（包含数据库名）
+     */
     getDbEndpoint(): string;
+    /**
+     * 获取数据库名称
+     */
     getDbName(): string;
+    /**
+     * 获取用户邮箱
+     */
     getEmail(): string;
+    /**
+     * 获取数据库密码
+     */
     getDbPassword(): string;
+    /**
+     * 获取用户目录
+     */
     getUserDir(): string;
+    /**
+     * 获取同步账号状态
+     */
     getStatus(): string;
+    /**
+     * 检查同步账号是否激活
+     */
     isActive(): boolean;
+    /**
+     * 获取 CouchDB URI（不包含数据库名）
+     * 例如：https://couch.example.com/dbname -> https://couch.example.com
+     */
     getCouchDbUri(): string;
+    /**
+     * 序列化为 JSON
+     */
     toJSON(): SyncConfigData;
+    /**
+     * 转换为 Obsidian LiveSync 插件格式
+     * 用于直接配置 Obsidian 的 LiveSync 插件
+     */
     toObsidianLiveSyncFormat(): {
         couchDB_URI: string;
         couchDB_DBNAME: string;
@@ -35,5 +79,8 @@ export declare class SyncConfig {
         syncOnSave: boolean;
         liveSync: boolean;
     };
+    /**
+     * 比较两个 SyncConfig 是否相同
+     */
     equals(other: SyncConfig): boolean;
 }