@uzqw/shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,708 @@
+import { z } from 'zod';
+
+interface RecolxConfig {
+    /** OAuth client id（developer 客户端注册名） */
+    clientId?: string;
+    /** OAuth 回调地址（本地 stdio 自收） */
+    redirectUri?: string;
+    /** token 落盘文件名（~/.recolx/ 内；默认 tokens-mcp.json 与 CLI 分离） */
+    tokenFile?: string;
+    /** token 落盘目录（测试注入用），默认 ~/.recolx */
+    tokenDir?: string;
+    /** API base，默认 http://127.0.0.1:8005（本地 dev） */
+    apiBase?: string;
+    /** 授权页地址；缺省 = `${apiBase}/open/oauth/authorize` */
+    authorizationUrl?: string;
+    /** token/refresh 端点；缺省 = `${apiBase}/open/oauth/token`（grant_type 区分） */
+    tokenUrl?: string;
+    /** 附加请求头 */
+    extraHeaders?: Record<string, string>;
+    /** fetch 实现（测试注入用），默认全局 fetch */
+    fetch?: typeof fetch;
+}
+declare const DEFAULT_API_BASE: string;
+declare const DEFAULT_CLIENT_ID: string;
+declare const DEFAULT_REDIRECT_URI = "http://localhost:8199/auth/callback";
+declare function resolveConfig(config: RecolxConfig): Required<Pick<RecolxConfig, "clientId" | "redirectUri" | "tokenFile" | "apiBase" | "authorizationUrl" | "tokenUrl">> & Pick<RecolxConfig, "extraHeaders" | "fetch" | "tokenDir">;
+
+interface TokenSet {
+    access_token: string;
+    refresh_token?: string;
+    token_type?: string;
+    /** 过期时间（epoch ms），由 expires_in 换算 */
+    expires_at?: number;
+    scope?: string;
+}
+declare class TokenStore {
+    readonly dir: string;
+    readonly path: string;
+    constructor(filename?: string, dir?: string);
+    save(tokenSet: TokenSet): Promise<void>;
+    load(): Promise<TokenSet | null>;
+    clear(): Promise<void>;
+}
+/** 默认 MCP token 落盘绝对路径（与 issue #5 的 ~/.recolx/tokens-mcp.json 一致） */
+declare const TOKENS_MCP_PATH: string;
+
+declare function generateCodeVerifier(): string;
+declare function generateCodeChallenge(verifier: string): string;
+declare function generateState(): string;
+interface AuthorizationRequest {
+    url: string;
+    codeVerifier: string;
+    state: string;
+}
+declare class OAuth {
+    readonly config: ReturnType<typeof resolveConfig>;
+    readonly tokenStore: TokenStore;
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    private readonly fetchImpl;
+    constructor(config: RecolxConfig);
+    /** 构造授权请求（PKCE S256）。extraParams 用于本地联调注入 user_id（env=local 才接受）。 */
+    createAuthorizationRequest(extraParams?: Record<string, string>): AuthorizationRequest;
+    /** 授权码换 token 并落盘；失败抛 Error（含状态码与响应体）。 */
+    exchangeCode(code: string, codeVerifier: string): Promise<TokenSet>;
+    /** 用 refresh_token 换新 token（后端滚动轮换），失败返回 null。 */
+    refresh(refreshToken: string): Promise<TokenSet | null>;
+    /** 取可用 access token：未过期直接用；过期则滚动刷新；失败返回 null。 */
+    getAccessToken(): Promise<string | null>;
+    /** 服务端撤销指定 token（RFC 7009：未知 token 也返回成功）。 */
+    revoke(token: string, tokenTypeHint?: string): Promise<void>;
+    /** 清空本地 token（logout 本地侧）。 */
+    logout(): Promise<void>;
+}
+
+declare class RecolxClient {
+    readonly oauth: OAuth;
+    readonly apiBase: string;
+    readonly extraHeaders: Record<string, string>;
+    /** 测试/联调用：设置后不再走 OAuth token 获取 */
+    staticToken?: string;
+    private readonly fetchImpl;
+    constructor(config: RecolxConfig);
+    get auth(): OAuth;
+    request(path: string, init?: RequestInit & {
+        token?: string;
+    }): Promise<unknown>;
+    /** GET /open/third-party/users/current */
+    getCurrentUser(): Promise<unknown>;
+    /** POST /open/third-party/users/current/revoke（撤销当前用户全部 MCP token） */
+    revokeCurrentUser(): Promise<unknown>;
+    /** GET /open/third-party/files?page=&page_size= */
+    listFiles(page?: number, pageSize?: number): Promise<unknown>;
+    /** GET /open/third-party/files/{id}[?include=transcript] */
+    getFile(fileId: string, opts?: {
+        includeTranscript?: boolean;
+    }): Promise<unknown>;
+}
+
+type RecolxErrorType = "auth" | "permission" | "not_found" | "timeout" | "network" | "server_error" | "client_error" | "unknown";
+declare function errorTypeFromStatus(status: number): RecolxErrorType;
+declare function classifyError(err: unknown): RecolxErrorType;
+
+declare const SubscriptionSchema: z.ZodObject<{
+    tier: z.ZodEnum<["free", "trial", "vip"]>;
+    is_trial: z.ZodBoolean;
+    subscribed: z.ZodBoolean;
+    vip_seconds_left: z.ZodNumber;
+    vip_seconds_total: z.ZodNumber;
+    pack_seconds_left: z.ZodNumber;
+    pack_seconds_total: z.ZodNumber;
+    device_seconds_left: z.ZodNumber;
+    device_seconds_total: z.ZodNumber;
+    space_total: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    tier: "free" | "trial" | "vip";
+    is_trial: boolean;
+    subscribed: boolean;
+    vip_seconds_left: number;
+    vip_seconds_total: number;
+    pack_seconds_left: number;
+    pack_seconds_total: number;
+    device_seconds_left: number;
+    device_seconds_total: number;
+    space_total: number;
+}, {
+    tier: "free" | "trial" | "vip";
+    is_trial: boolean;
+    subscribed: boolean;
+    vip_seconds_left: number;
+    vip_seconds_total: number;
+    pack_seconds_left: number;
+    pack_seconds_total: number;
+    device_seconds_left: number;
+    device_seconds_total: number;
+    space_total: number;
+}>;
+type RecolxSubscription = z.infer<typeof SubscriptionSchema>;
+declare const CurrentUserSchema: z.ZodObject<{
+    user_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    nickname: z.ZodString;
+    subscription: z.ZodObject<{
+        tier: z.ZodEnum<["free", "trial", "vip"]>;
+        is_trial: z.ZodBoolean;
+        subscribed: z.ZodBoolean;
+        vip_seconds_left: z.ZodNumber;
+        vip_seconds_total: z.ZodNumber;
+        pack_seconds_left: z.ZodNumber;
+        pack_seconds_total: z.ZodNumber;
+        device_seconds_left: z.ZodNumber;
+        device_seconds_total: z.ZodNumber;
+        space_total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        tier: "free" | "trial" | "vip";
+        is_trial: boolean;
+        subscribed: boolean;
+        vip_seconds_left: number;
+        vip_seconds_total: number;
+        pack_seconds_left: number;
+        pack_seconds_total: number;
+        device_seconds_left: number;
+        device_seconds_total: number;
+        space_total: number;
+    }, {
+        tier: "free" | "trial" | "vip";
+        is_trial: boolean;
+        subscribed: boolean;
+        vip_seconds_left: number;
+        vip_seconds_total: number;
+        pack_seconds_left: number;
+        pack_seconds_total: number;
+        device_seconds_left: number;
+        device_seconds_total: number;
+        space_total: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    user_id: string | number;
+    nickname: string;
+    subscription: {
+        tier: "free" | "trial" | "vip";
+        is_trial: boolean;
+        subscribed: boolean;
+        vip_seconds_left: number;
+        vip_seconds_total: number;
+        pack_seconds_left: number;
+        pack_seconds_total: number;
+        device_seconds_left: number;
+        device_seconds_total: number;
+        space_total: number;
+    };
+}, {
+    user_id: string | number;
+    nickname: string;
+    subscription: {
+        tier: "free" | "trial" | "vip";
+        is_trial: boolean;
+        subscribed: boolean;
+        vip_seconds_left: number;
+        vip_seconds_total: number;
+        pack_seconds_left: number;
+        pack_seconds_total: number;
+        device_seconds_left: number;
+        device_seconds_total: number;
+        space_total: number;
+    };
+}>;
+type RecolxCurrentUser = z.infer<typeof CurrentUserSchema>;
+declare const DeviceSchema: z.ZodObject<{
+    name: z.ZodString;
+    serial: z.ZodString;
+    /** 型号：earphone/recorder/recolx_fit/card/unknown（后端按 SN 白名单解析） */
+    model: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    serial: string;
+    model: string;
+}, {
+    name: string;
+    serial: string;
+    model: string;
+}>;
+type RecolxDevice = z.infer<typeof DeviceSchema>;
+declare const FileSchema: z.ZodObject<{
+    file_id: z.ZodString;
+    title: z.ZodString;
+    /** Unix 秒 */
+    recorded_at: z.ZodNumber;
+    /** 秒 */
+    duration: z.ZodNumber;
+    /** 字节 */
+    file_size: z.ZodNumber;
+    device: z.ZodObject<{
+        name: z.ZodString;
+        serial: z.ZodString;
+        /** 型号：earphone/recorder/recolx_fit/card/unknown（后端按 SN 白名单解析） */
+        model: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        serial: string;
+        model: string;
+    }, {
+        name: string;
+        serial: string;
+        model: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    file_id: string;
+    title: string;
+    recorded_at: number;
+    duration: number;
+    file_size: number;
+    device: {
+        name: string;
+        serial: string;
+        model: string;
+    };
+}, {
+    file_id: string;
+    title: string;
+    recorded_at: number;
+    duration: number;
+    file_size: number;
+    device: {
+        name: string;
+        serial: string;
+        model: string;
+    };
+}>;
+type RecolxFile = z.infer<typeof FileSchema>;
+declare const FileListSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        file_id: z.ZodString;
+        title: z.ZodString;
+        /** Unix 秒 */
+        recorded_at: z.ZodNumber;
+        /** 秒 */
+        duration: z.ZodNumber;
+        /** 字节 */
+        file_size: z.ZodNumber;
+        device: z.ZodObject<{
+            name: z.ZodString;
+            serial: z.ZodString;
+            /** 型号：earphone/recorder/recolx_fit/card/unknown（后端按 SN 白名单解析） */
+            model: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            serial: string;
+            model: string;
+        }, {
+            name: string;
+            serial: string;
+            model: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        file_id: string;
+        title: string;
+        recorded_at: number;
+        duration: number;
+        file_size: number;
+        device: {
+            name: string;
+            serial: string;
+            model: string;
+        };
+    }, {
+        file_id: string;
+        title: string;
+        recorded_at: number;
+        duration: number;
+        file_size: number;
+        device: {
+            name: string;
+            serial: string;
+            model: string;
+        };
+    }>, "many">;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    page_size: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    files: {
+        file_id: string;
+        title: string;
+        recorded_at: number;
+        duration: number;
+        file_size: number;
+        device: {
+            name: string;
+            serial: string;
+            model: string;
+        };
+    }[];
+    total: number;
+    page: number;
+    page_size: number;
+}, {
+    files: {
+        file_id: string;
+        title: string;
+        recorded_at: number;
+        duration: number;
+        file_size: number;
+        device: {
+            name: string;
+            serial: string;
+            model: string;
+        };
+    }[];
+    total: number;
+    page: number;
+    page_size: number;
+}>;
+type RecolxFileList = z.infer<typeof FileListSchema>;
+declare const SegmentSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    text: z.ZodString;
+    speaker: z.ZodString;
+    language: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    start: number;
+    end: number;
+    text: string;
+    speaker: string;
+    language: string;
+}, {
+    start: number;
+    end: number;
+    text: string;
+    speaker: string;
+    language: string;
+}>;
+type RecolxSegment = z.infer<typeof SegmentSchema>;
+declare const SummarySchema: z.ZodObject<{
+    task_id: z.ZodString;
+    text: z.ZodString;
+    prompt_id: z.ZodString;
+    prompt_name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    task_id: string;
+    prompt_id: string;
+    prompt_name: string;
+}, {
+    text: string;
+    task_id: string;
+    prompt_id: string;
+    prompt_name: string;
+}>;
+type RecolxSummary = z.infer<typeof SummarySchema>;
+/** 转写/总结（?include=transcript 时附加；空数据后端返回 null，按 null 与 [] 双兼容处理） */
+declare const TranscriptSchema: z.ZodObject<{
+    language: z.ZodString;
+    segments: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        text: z.ZodString;
+        speaker: z.ZodString;
+        language: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        start: number;
+        end: number;
+        text: string;
+        speaker: string;
+        language: string;
+    }, {
+        start: number;
+        end: number;
+        text: string;
+        speaker: string;
+        language: string;
+    }>, "many">>;
+    summary: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        task_id: z.ZodString;
+        text: z.ZodString;
+        prompt_id: z.ZodString;
+        prompt_name: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        task_id: string;
+        prompt_id: string;
+        prompt_name: string;
+    }, {
+        text: string;
+        task_id: string;
+        prompt_id: string;
+        prompt_name: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    language: string;
+    segments: {
+        start: number;
+        end: number;
+        text: string;
+        speaker: string;
+        language: string;
+    }[] | null;
+    summary: {
+        text: string;
+        task_id: string;
+        prompt_id: string;
+        prompt_name: string;
+    }[] | null;
+}, {
+    language: string;
+    segments: {
+        start: number;
+        end: number;
+        text: string;
+        speaker: string;
+        language: string;
+    }[] | null;
+    summary: {
+        text: string;
+        task_id: string;
+        prompt_id: string;
+        prompt_name: string;
+    }[] | null;
+}>;
+type RecolxTranscript = z.infer<typeof TranscriptSchema>;
+declare const FileDetailSchema: z.ZodObject<{
+    file_id: z.ZodString;
+    title: z.ZodString;
+    /** Unix 秒 */
+    recorded_at: z.ZodNumber;
+    /** 秒 */
+    duration: z.ZodNumber;
+    /** 字节 */
+    file_size: z.ZodNumber;
+    device: z.ZodObject<{
+        name: z.ZodString;
+        serial: z.ZodString;
+        /** 型号：earphone/recorder/recolx_fit/card/unknown（后端按 SN 白名单解析） */
+        model: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        serial: string;
+        model: string;
+    }, {
+        name: string;
+        serial: string;
+        model: string;
+    }>;
+} & {
+    /** 24h 音频下载地址（presign JWT 在 query） */
+    presigned_url: z.ZodString;
+    /** Unix 秒 */
+    presigned_url_expires_at: z.ZodNumber;
+    transcript: z.ZodOptional<z.ZodObject<{
+        language: z.ZodString;
+        segments: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            text: z.ZodString;
+            speaker: z.ZodString;
+            language: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }, {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }>, "many">>;
+        summary: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            task_id: z.ZodString;
+            text: z.ZodString;
+            prompt_id: z.ZodString;
+            prompt_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }, {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        language: string;
+        segments: {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }[] | null;
+        summary: {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }[] | null;
+    }, {
+        language: string;
+        segments: {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }[] | null;
+        summary: {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }[] | null;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    file_id: string;
+    title: string;
+    recorded_at: number;
+    duration: number;
+    file_size: number;
+    device: {
+        name: string;
+        serial: string;
+        model: string;
+    };
+    presigned_url: string;
+    presigned_url_expires_at: number;
+    transcript?: {
+        language: string;
+        segments: {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }[] | null;
+        summary: {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }[] | null;
+    } | undefined;
+}, {
+    file_id: string;
+    title: string;
+    recorded_at: number;
+    duration: number;
+    file_size: number;
+    device: {
+        name: string;
+        serial: string;
+        model: string;
+    };
+    presigned_url: string;
+    presigned_url_expires_at: number;
+    transcript?: {
+        language: string;
+        segments: {
+            start: number;
+            end: number;
+            text: string;
+            speaker: string;
+            language: string;
+        }[] | null;
+        summary: {
+            text: string;
+            task_id: string;
+            prompt_id: string;
+            prompt_name: string;
+        }[] | null;
+    } | undefined;
+}>;
+type RecolxFileDetail = z.infer<typeof FileDetailSchema>;
+declare const LoginInput: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+declare const LogoutInput: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+declare const GetCurrentUserInput: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+declare const ListFilesInput: z.ZodObject<{
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page_size: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    query: z.ZodOptional<z.ZodString>;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    page_size: number;
+    query?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+}, {
+    page?: number | undefined;
+    page_size?: number | undefined;
+    query?: string | undefined;
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+}>;
+declare const GetFileInput: z.ZodObject<{
+    file_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file_id: string;
+}, {
+    file_id: string;
+}>;
+declare const GetNoteInput: z.ZodObject<{
+    file_id: z.ZodString;
+    template: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    file_id: string;
+    template?: string | undefined;
+}, {
+    file_id: string;
+    template?: string | undefined;
+}>;
+declare const GetTranscriptInput: z.ZodObject<{
+    file_id: z.ZodString;
+    cursor: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    speaker: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<["raw", "polish"]>>;
+}, "strip", z.ZodTypeAny, {
+    file_id: string;
+    speaker?: string | undefined;
+    language?: string | undefined;
+    cursor?: string | undefined;
+    mode?: "raw" | "polish" | undefined;
+}, {
+    file_id: string;
+    speaker?: string | undefined;
+    language?: string | undefined;
+    cursor?: string | undefined;
+    mode?: "raw" | "polish" | undefined;
+}>;
+
+/** 解析 API 时间戳（秒/ISO）→ epoch ms；无效返回 null。 */
+declare function parseApiTimestamp(value: string | undefined | null): number | null;
+/** 某日 00:00:00（本地时区）→ epoch ms；无效日期返回 null。 */
+declare function localDayStart(value: string | undefined | null): number | null;
+/** 某日 23:59:59.999 → epoch ms；无效日期返回 null。 */
+declare function localDayEnd(value: string | undefined | null): number | null;
+
+type OAuthCallbackResult = {
+    status: "success";
+} | {
+    status: "denied";
+    error: Error;
+} | {
+    status: "exchange-failed";
+    error: Error;
+} | {
+    status: "timeout";
+} | {
+    status: "listen-failed";
+    error: Error;
+};
+interface RunOAuthCallbackOpts {
+    port: number;
+    expectedState: string;
+    exchangeCode: (code: string) => Promise<unknown>;
+    timeoutMs?: number;
+    onListening?: () => void;
+    /** 成功后延时关服，保证页面渲染完（默认 1.5s） */
+    postSuccessDelayMs?: number;
+}
+declare function runOAuthCallback(opts: RunOAuthCallbackOpts): Promise<OAuthCallbackResult>;
+
+export { type AuthorizationRequest, CurrentUserSchema, DEFAULT_API_BASE, DEFAULT_CLIENT_ID, DEFAULT_REDIRECT_URI, DeviceSchema, FileDetailSchema, FileListSchema, FileSchema, GetCurrentUserInput, GetFileInput, GetNoteInput, GetTranscriptInput, ListFilesInput, LoginInput, LogoutInput, OAuth, type OAuthCallbackResult, RecolxClient, type RecolxConfig, type RecolxCurrentUser, type RecolxDevice, type RecolxErrorType, type RecolxFile, type RecolxFileDetail, type RecolxFileList, type RecolxSegment, type RecolxSubscription, type RecolxSummary, type RecolxTranscript, type RunOAuthCallbackOpts, SegmentSchema, SubscriptionSchema, SummarySchema, TOKENS_MCP_PATH, type TokenSet, TokenStore, TranscriptSchema, classifyError, errorTypeFromStatus, generateCodeChallenge, generateCodeVerifier, generateState, localDayEnd, localDayStart, parseApiTimestamp, resolveConfig, runOAuthCallback };

package/dist/index.js

@@ -0,0 +1,493 @@
+// src/config.ts
+var DEFAULT_API_BASE = process.env.RECOLX_API_BASE ?? "http://127.0.0.1:8005";
+var DEFAULT_CLIENT_ID = process.env.RECOLX_MCP_CLIENT_ID ?? "recolx-mcp";
+var DEFAULT_REDIRECT_URI = "http://localhost:8199/auth/callback";
+function resolveConfig(config) {
+  const apiBase = (config.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  return {
+    clientId: config.clientId ?? DEFAULT_CLIENT_ID,
+    redirectUri: config.redirectUri ?? DEFAULT_REDIRECT_URI,
+    tokenFile: config.tokenFile ?? "tokens-mcp.json",
+    apiBase,
+    authorizationUrl: config.authorizationUrl ?? `${apiBase}/open/oauth/authorize`,
+    tokenUrl: config.tokenUrl ?? `${apiBase}/open/oauth/token`,
+    extraHeaders: config.extraHeaders ?? {},
+    fetch: config.fetch,
+    tokenDir: config.tokenDir
+  };
+}
+
+// src/token-store.ts
+import { readFile, writeFile, mkdir, rm } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+var TokenStore = class {
+  dir;
+  path;
+  constructor(filename = "tokens-mcp.json", dir = join(homedir(), ".recolx")) {
+    this.dir = dir;
+    this.path = join(dir, filename);
+  }
+  async save(tokenSet) {
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(this.path, JSON.stringify(tokenSet, null, 2) + "\n", "utf-8");
+  }
+  async load() {
+    try {
+      return JSON.parse(await readFile(this.path, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+  async clear() {
+    try {
+      await rm(this.path);
+    } catch {
+    }
+  }
+};
+var TOKENS_MCP_PATH = join(homedir(), ".recolx", "tokens-mcp.json");
+
+// src/oauth.ts
+import { createHash, randomBytes } from "crypto";
+function generateCodeVerifier() {
+  return randomBytes(32).toString("base64url");
+}
+function generateCodeChallenge(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+function generateState() {
+  return randomBytes(16).toString("base64url");
+}
+function toTokenSet(data) {
+  return {
+    access_token: String(data.access_token ?? ""),
+    refresh_token: data.refresh_token ? String(data.refresh_token) : void 0,
+    token_type: data.token_type ? String(data.token_type) : "Bearer",
+    expires_at: typeof data.expires_in === "number" ? Date.now() + data.expires_in * 1e3 : void 0,
+    scope: data.scope ? String(data.scope) : void 0
+  };
+}
+var OAuth = class {
+  config;
+  tokenStore;
+  authorizationUrl;
+  tokenUrl;
+  fetchImpl;
+  constructor(config) {
+    this.config = resolveConfig(config);
+    this.tokenStore = new TokenStore(this.config.tokenFile, this.config.tokenDir);
+    this.authorizationUrl = this.config.authorizationUrl;
+    this.tokenUrl = this.config.tokenUrl;
+    this.fetchImpl = this.config.fetch ?? fetch;
+  }
+  /** 构造授权请求（PKCE S256）。extraParams 用于本地联调注入 user_id（env=local 才接受）。 */
+  createAuthorizationRequest(extraParams = {}) {
+    const codeVerifier = generateCodeVerifier();
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      response_type: "code",
+      scope: "read",
+      code_challenge: generateCodeChallenge(codeVerifier),
+      code_challenge_method: "S256",
+      state: generateState(),
+      ...extraParams
+    });
+    return { url: `${this.authorizationUrl}?${params.toString()}`, codeVerifier, state: params.get("state") };
+  }
+  /** 授权码换 token 并落盘；失败抛 Error（含状态码与响应体）。 */
+  async exchangeCode(code, codeVerifier) {
+    const res = await this.fetchImpl(this.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body: new URLSearchParams({ grant_type: "authorization_code", code, code_verifier: codeVerifier })
+    });
+    if (!res.ok) {
+      throw new Error(`Token exchange failed: ${res.status} ${await res.text()}`);
+    }
+    const tokenSet = toTokenSet(await res.json());
+    await this.tokenStore.save(tokenSet);
+    return tokenSet;
+  }
+  /** 用 refresh_token 换新 token（后端滚动轮换），失败返回 null。 */
+  async refresh(refreshToken) {
+    const res = await this.fetchImpl(this.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken })
+    });
+    if (!res.ok) {
+      throw new Error(`Token refresh failed: ${res.status} ${await res.text()}`);
+    }
+    const tokenSet = toTokenSet(await res.json());
+    await this.tokenStore.save(tokenSet);
+    return tokenSet;
+  }
+  /** 取可用 access token：未过期直接用；过期则滚动刷新；失败返回 null。 */
+  async getAccessToken() {
+    const tokenSet = await this.tokenStore.load();
+    if (!tokenSet?.access_token) return null;
+    const expired = tokenSet.expires_at !== void 0 && Date.now() > tokenSet.expires_at - 6e4;
+    if (expired) {
+      if (!tokenSet.refresh_token) return null;
+      try {
+        return (await this.refresh(tokenSet.refresh_token))?.access_token ?? null;
+      } catch {
+        return null;
+      }
+    }
+    return tokenSet.access_token;
+  }
+  /** 服务端撤销指定 token（RFC 7009：未知 token 也返回成功）。 */
+  async revoke(token, tokenTypeHint) {
+    const body = { token };
+    if (tokenTypeHint) body.token_type_hint = tokenTypeHint;
+    await this.fetchImpl(`${this.config.apiBase}/open/oauth/revoke`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body: new URLSearchParams(body)
+    });
+  }
+  /** 清空本地 token（logout 本地侧）。 */
+  async logout() {
+    await this.tokenStore.clear();
+  }
+};
+
+// src/client.ts
+var RecolxClient = class {
+  oauth;
+  apiBase;
+  extraHeaders;
+  /** 测试/联调用：设置后不再走 OAuth token 获取 */
+  staticToken;
+  fetchImpl;
+  constructor(config) {
+    const resolved = resolveConfig(config);
+    this.oauth = new OAuth(resolved);
+    this.apiBase = resolved.apiBase;
+    this.extraHeaders = resolved.extraHeaders ?? {};
+    this.fetchImpl = resolved.fetch ?? fetch;
+  }
+  get auth() {
+    return this.oauth;
+  }
+  async request(path, init) {
+    const token = init?.token ?? this.staticToken ?? await this.oauth.getAccessToken();
+    if (!token) {
+      throw new Error("\u672A\u767B\u5F55\uFF1A\u8BF7\u5148\u8FD0\u884C recolx-mcp login");
+    }
+    const url = `${this.apiBase}${path}`;
+    const res = await this.fetchImpl(url, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        ...this.extraHeaders,
+        ...init?.headers ?? {}
+      }
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      const detail = body.length > 0 ? `: ${body.slice(0, 300)}` : "";
+      throw new Error(`API error: ${res.status} ${res.statusText}${detail}`);
+    }
+    return res.json();
+  }
+  /** GET /open/third-party/users/current */
+  getCurrentUser() {
+    return this.request("/open/third-party/users/current");
+  }
+  /** POST /open/third-party/users/current/revoke（撤销当前用户全部 MCP token） */
+  revokeCurrentUser() {
+    return this.request("/open/third-party/users/current/revoke", { method: "POST" });
+  }
+  /** GET /open/third-party/files?page=&page_size= */
+  listFiles(page = 1, pageSize = 20) {
+    return this.request(`/open/third-party/files?page=${page}&page_size=${pageSize}`);
+  }
+  /** GET /open/third-party/files/{id}[?include=transcript] */
+  getFile(fileId, opts = {}) {
+    const qs = opts.includeTranscript ? "?include=transcript" : "";
+    return this.request(`/open/third-party/files/${encodeURIComponent(fileId)}${qs}`);
+  }
+};
+
+// src/errors.ts
+function errorTypeFromStatus(status) {
+  if (status === 401) return "auth";
+  if (status === 403) return "permission";
+  if (status === 404) return "not_found";
+  if (status >= 500) return "server_error";
+  if (status >= 400) return "client_error";
+  return "unknown";
+}
+function classifyError(err) {
+  const e = err instanceof Error ? err : void 0;
+  const msg = e ? e.message : String(err ?? "");
+  const name = e ? e.name : "";
+  if (name === "AbortError" || /\btimeout\b|ETIMEDOUT/i.test(msg)) return "timeout";
+  if (err instanceof TypeError || /fetch failed|ECONNREFUSED|ENOTFOUND|ECONNRESET|EAI_AGAIN|network/i.test(msg)) return "network";
+  if (/\b401\b|not authenticated|unauthorized|未登录/i.test(msg)) return "auth";
+  if (/\b403\b|forbidden/i.test(msg)) return "permission";
+  if (/\b404\b|not found/i.test(msg)) return "not_found";
+  if (/\b5\d\d\b|internal server error|bad gateway|service unavailable|gateway timeout/i.test(msg)) return "server_error";
+  if (/\b4\d\d\b/.test(msg)) return "client_error";
+  return "unknown";
+}
+
+// src/schemas.ts
+import { z } from "zod";
+var SubscriptionSchema = z.object({
+  tier: z.enum(["free", "trial", "vip"]),
+  is_trial: z.boolean(),
+  subscribed: z.boolean(),
+  vip_seconds_left: z.number(),
+  vip_seconds_total: z.number(),
+  pack_seconds_left: z.number(),
+  pack_seconds_total: z.number(),
+  device_seconds_left: z.number(),
+  device_seconds_total: z.number(),
+  space_total: z.number()
+});
+var CurrentUserSchema = z.object({
+  // 后端输出 string（雪花 ID 防 JS 精度丢失）；兼容历史 number 输出。
+  user_id: z.union([z.string(), z.number()]),
+  nickname: z.string(),
+  subscription: SubscriptionSchema
+});
+var DeviceSchema = z.object({
+  name: z.string(),
+  serial: z.string(),
+  /** 型号：earphone/recorder/recolx_fit/card/unknown（后端按 SN 白名单解析） */
+  model: z.string()
+});
+var FileSchema = z.object({
+  file_id: z.string(),
+  title: z.string(),
+  /** Unix 秒 */
+  recorded_at: z.number(),
+  /** 秒 */
+  duration: z.number(),
+  /** 字节 */
+  file_size: z.number(),
+  device: DeviceSchema
+});
+var FileListSchema = z.object({
+  files: z.array(FileSchema),
+  total: z.number(),
+  page: z.number(),
+  page_size: z.number()
+});
+var SegmentSchema = z.object({
+  start: z.number(),
+  end: z.number(),
+  text: z.string(),
+  speaker: z.string(),
+  language: z.string()
+});
+var SummarySchema = z.object({
+  task_id: z.string(),
+  text: z.string(),
+  prompt_id: z.string(),
+  prompt_name: z.string()
+});
+var TranscriptSchema = z.object({
+  language: z.string(),
+  segments: z.array(SegmentSchema).nullable(),
+  summary: z.array(SummarySchema).nullable()
+});
+var FileDetailSchema = FileSchema.extend({
+  /** 24h 音频下载地址（presign JWT 在 query） */
+  presigned_url: z.string(),
+  /** Unix 秒 */
+  presigned_url_expires_at: z.number(),
+  transcript: TranscriptSchema.optional()
+});
+var LoginInput = z.object({}).optional();
+var LogoutInput = z.object({}).optional();
+var GetCurrentUserInput = z.object({}).optional();
+var ListFilesInput = z.object({
+  page: z.number().int().min(1).optional().default(1),
+  page_size: z.number().int().min(1).max(100).optional().default(20),
+  query: z.string().optional().describe("\u6807\u9898\u5927\u5C0F\u5199\u4E0D\u654F\u611F\u5B50\u4E32\u8FC7\u6EE4\uFF08MCP \u4FA7\u5BA2\u6237\u7AEF\u8FC7\u6EE4\uFF09"),
+  date_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("\u5F00\u59CB\u65E5\u671F\uFF08\u542B\uFF09\uFF0CYYYY-MM-DD\uFF0C\u6309\u670D\u52A1\u7AEF\u65F6\u533A"),
+  date_to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("\u7ED3\u675F\u65E5\u671F\uFF08\u542B\uFF09\uFF0CYYYY-MM-DD\uFF0C\u6309\u670D\u52A1\u7AEF\u65F6\u533A")
+});
+var GetFileInput = z.object({
+  file_id: z.string().min(1).describe("\u5F55\u97F3\u6587\u4EF6 ID")
+});
+var GetNoteInput = z.object({
+  file_id: z.string().min(1).describe("\u5F55\u97F3\u6587\u4EF6 ID"),
+  template: z.string().optional().describe("\u6A21\u677F\u540D/\u6A21\u677F id\uFF08\u6309\u6A21\u677F tab \u5B9A\u4F4D\uFF1B\u7F3A\u7701\u8FD4\u56DE\u5168\u90E8\u6458\u8981\uFF09")
+});
+var GetTranscriptInput = z.object({
+  file_id: z.string().min(1).describe("\u5F55\u97F3\u6587\u4EF6 ID"),
+  cursor: z.string().optional().describe("\u4E0A\u4E00\u9875\u8FD4\u56DE\u7684\u7FFB\u9875\u6E38\u6807"),
+  language: z.string().optional().describe("\u6309\u8BED\u8A00\u8FC7\u6EE4\uFF08\u5982 zh\u3001en\uFF09"),
+  speaker: z.string().optional().describe("\u6309\u8BF4\u8BDD\u4EBA\u8FC7\u6EE4"),
+  mode: z.enum(["raw", "polish"]).optional().describe("\u9ED8\u8BA4 raw \u539F\u6587\uFF1Bpolish \u6DA6\u8272")
+});
+
+// src/time.ts
+var HAS_TIMEZONE = /(?:[Zz]|[+-]\d{2}(?::?\d{2})?)$/;
+var HAS_TIME = /\d{2}:\d{2}/;
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function parseApiTimestamp(value) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const normalised = HAS_TIME.test(trimmed) && !HAS_TIMEZONE.test(trimmed) ? `${trimmed}Z` : trimmed;
+  const ms = new Date(normalised).getTime();
+  return Number.isNaN(ms) ? null : ms;
+}
+function parseDateOnly(value) {
+  if (!value) return null;
+  const match = DATE_ONLY.exec(value.trim());
+  if (!match) return null;
+  const y = Number(match[1]);
+  const m = Number(match[2]);
+  const d = Number(match[3]);
+  const probe = new Date(y, m - 1, d);
+  if (probe.getFullYear() !== y || probe.getMonth() !== m - 1 || probe.getDate() !== d) return null;
+  return [y, m, d];
+}
+function localDayStart(value) {
+  const parts = parseDateOnly(value);
+  if (!parts) return null;
+  const [y, m, d] = parts;
+  return new Date(y, m - 1, d, 0, 0, 0, 0).getTime();
+}
+function localDayEnd(value) {
+  const parts = parseDateOnly(value);
+  if (!parts) return null;
+  const [y, m, d] = parts;
+  return new Date(y, m - 1, d + 1, 0, 0, 0, 0).getTime() - 1;
+}
+
+// src/callback.ts
+import { createServer } from "http";
+var SUCCESS_HTML = '<!doctype html><html><head><meta charset="utf-8"><title>Recolx</title></head><body style="font-family:system-ui;padding:2rem;text-align:center;"><h1>\u6388\u6743\u6210\u529F\uFF01</h1><p>\u4F60\u53EF\u4EE5\u5173\u95ED\u6B64\u9875\u9762\uFF0C\u56DE\u5230\u539F\u7A97\u53E3\u7EE7\u7EED\u3002</p></body></html>';
+var NEUTRAL_HTML = '<!doctype html><html><head><meta charset="utf-8"><title>Recolx</title></head><body style="font-family:system-ui;padding:2rem;text-align:center;"><h1>\u8BF7\u56DE\u5230\u539F\u7A97\u53E3\u7EE7\u7EED\u6388\u6743\u3002</h1><p>\u6B64\u9875\u9762\u53EF\u5173\u95ED\u3002</p></body></html>';
+var ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+function errorHtml(message) {
+  const escaped = (message ?? "").replace(/[&<>]/g, (c) => ESC[c] ?? c);
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Recolx</title></head><body style="font-family:system-ui;padding:2rem;text-align:center;"><h1>\u6388\u6743\u5931\u8D25</h1><pre style="white-space:pre-wrap;">${escaped}</pre></body></html>`;
+}
+function runOAuthCallback(opts) {
+  const { port, expectedState, exchangeCode, timeoutMs = 12e4, postSuccessDelayMs = 1500, onListening } = opts;
+  return new Promise((resolve) => {
+    let settled = false;
+    let exchangeStarted = false;
+    let exchangeSucceeded = false;
+    let timeoutId = null;
+    let closeTimeoutId = null;
+    const finalize = (result, immediate = false) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      const close = () => {
+        try {
+          server.closeAllConnections?.();
+        } catch {
+        }
+        server.close(() => resolve(result));
+      };
+      if (immediate || result.status !== "success") close();
+      else {
+        closeTimeoutId = setTimeout(close, postSuccessDelayMs);
+        closeTimeoutId.unref?.();
+      }
+    };
+    const server = createServer((req, res) => {
+      const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+      if (reqUrl.pathname !== "/auth/callback") {
+        res.writeHead(404, { "Content-Type": "text/html" });
+        res.end(errorHtml("404 Not Found"));
+        return;
+      }
+      const params = reqUrl.searchParams;
+      const error = params.get("error");
+      const state = params.get("state");
+      const code = params.get("code");
+      const respond = (html, status = 200) => {
+        res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+      };
+      if (error) {
+        const desc = params.get("error_description") ?? error;
+        respond(errorHtml(`\u6388\u6743\u88AB\u62D2\u7EDD\uFF1A${desc}`), 400);
+        finalize({ status: "denied", error: new Error(desc) });
+        return;
+      }
+      if (!state || state !== expectedState) {
+        respond(NEUTRAL_HTML);
+        return;
+      }
+      if (exchangeSucceeded) {
+        respond(SUCCESS_HTML);
+        return;
+      }
+      if (!code || exchangeStarted) {
+        respond(NEUTRAL_HTML);
+        return;
+      }
+      exchangeStarted = true;
+      exchangeCode(code).then(
+        () => {
+          exchangeSucceeded = true;
+          respond(SUCCESS_HTML);
+          finalize({ status: "success" });
+        },
+        (err) => {
+          const e = err instanceof Error ? err : new Error(String(err));
+          respond(errorHtml(e.message), 500);
+          finalize({ status: "exchange-failed", error: e });
+        }
+      );
+    });
+    server.on("error", (err) => {
+      if (settled) return;
+      const message = err.code === "EADDRINUSE" ? `\u7AEF\u53E3 ${port} \u88AB\u5360\u7528 \u2014\u2014 \u53EF\u80FD\u5DF2\u6709\u53E6\u4E00\u4E2A recolx login \u5728\u8FD0\u884C\u3002\u7A0D\u7B49\u51E0\u79D2\u91CD\u8BD5\u3002` : `\u56DE\u8C03\u670D\u52A1\u5668\u9519\u8BEF\uFF1A${err.message}`;
+      finalize({ status: "listen-failed", error: new Error(message) }, true);
+    });
+    timeoutId = setTimeout(() => finalize({ status: "timeout" }, true), timeoutMs);
+    server.listen(port, () => onListening?.());
+  });
+}
+export {
+  CurrentUserSchema,
+  DEFAULT_API_BASE,
+  DEFAULT_CLIENT_ID,
+  DEFAULT_REDIRECT_URI,
+  DeviceSchema,
+  FileDetailSchema,
+  FileListSchema,
+  FileSchema,
+  GetCurrentUserInput,
+  GetFileInput,
+  GetNoteInput,
+  GetTranscriptInput,
+  ListFilesInput,
+  LoginInput,
+  LogoutInput,
+  OAuth,
+  RecolxClient,
+  SegmentSchema,
+  SubscriptionSchema,
+  SummarySchema,
+  TOKENS_MCP_PATH,
+  TokenStore,
+  TranscriptSchema,
+  classifyError,
+  errorTypeFromStatus,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  localDayEnd,
+  localDayStart,
+  parseApiTimestamp,
+  resolveConfig,
+  runOAuthCallback
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@uzqw/shared",
+  "version": "0.1.0",
+  "description": "Shared types, zod schemas, token store and API client for recolx MCP/CLI",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  }
+}