timarai-dashboard-mcp 1.0.3

package/dist/client.js

@@ -0,0 +1,284 @@
+/**
+ * 平台驾驶舱 OpenAPI 客户端。
+ *
+ * 这里集中处理三件在真实调用中最容易出错的事：
+ * 1. **rawBody 一致性**：签名串必须与实际发送的字节原文逐字节一致，
+ *    所以本文件自行 JSON.stringify 并直接作为 fetch body，绝不让请求库二次序列化。
+ * 2. **±30 秒时钟偏斜**：Sandbox/Production 强制校验。本地时钟漂移时，
+ *    用响应的 `Date` 头估算服务端时间并做一次性偏斜校正后重试。
+ * 3. **错误归一化**：把 `CryptoApiResponse` 的数字码翻译成 Agent 能据此行动的建议。
+ */
+import { randomUUID } from "node:crypto";
+import { redactSecret } from "./config.js";
+import { buildSignedHeaders, timestampMillis } from "./signature.js";
+import { DASHBOARD_ROUTE_PREFIX } from "./registry.js";
+/** 接口契约约定的业务码（成功码对外为字符串 "0"）。 */
+export const API_CODE = {
+    SUCCESS: "0",
+    PARAMETER_INVALID: "400",
+    SIGNATURES_NOT_MATCH: "401",
+    UNAUTHORIZED: "403",
+    SERVER_ERROR: "500",
+};
+export class ApiError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.name = "ApiError";
+        this.detail = detail;
+    }
+}
+/** 响应外壳在部分网关包装下可能多一层 result，这里做宽容解析。 */
+function unwrapEnvelope(payload) {
+    if (payload && typeof payload === "object") {
+        const obj = payload;
+        if (obj.code !== undefined || obj.data !== undefined)
+            return obj;
+        if (obj.result !== undefined && typeof obj.result === "object") {
+            const inner = obj.result;
+            return { code: inner.code, msg: inner.msg, data: inner.data };
+        }
+    }
+    return {};
+}
+function describeFailure(code, msg) {
+    const text = `${msg}`;
+    switch (code) {
+        case API_CODE.SIGNATURES_NOT_MATCH:
+            return {
+                hint: "签名不匹配。检查：Secret 是否为数据字典 PlatformDashboardOpenApi 中该 clientId 的明文密钥；" +
+                    "时间戳是否为 Unix 毫秒；签名串是否为 timestamp+requestId+rawBody。",
+            };
+        case API_CODE.UNAUTHORIZED:
+            return {
+                hint: "无权限。检查：clientId 是否存在、enabled 是否为 true、scopes 是否包含 dashboard.read；" +
+                    "注意平台凭证与商户 X-Api-Key 不可混用。",
+            };
+        case API_CODE.PARAMETER_INVALID:
+            if (/timestamp/i.test(text)) {
+                return { hint: "时间戳超出 ±30 秒窗口。请校准 MCP 宿主机时钟（建议开启 NTP 自动同步）。" };
+            }
+            return { hint: "参数不合法或缺少鉴权 Header。请检查筛选值与必填字段。" };
+        case API_CODE.SERVER_ERROR:
+            if (/dictionary|unavailable/i.test(text)) {
+                return {
+                    hint: "服务端数据字典未配置（DictionaryMissing）。请让管理员在数据字典中写入 " +
+                        "Code=PlatformDashboardOpenApi 的平台 OpenAPI 配置项。",
+                };
+            }
+            return { hint: "服务端错误。请携带 requestId 联系平台侧排查。" };
+        default:
+            return { hint: "调用失败，请结合 code 与 msg 排查。" };
+    }
+}
+/** 幂等的简单 TTL 缓存，仅用于筛选选项这类低频变动数据。 */
+class TtlCache {
+    ttlMs;
+    store = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const hit = this.store.get(key);
+        if (!hit)
+            return undefined;
+        if (hit.expiresAt < Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return hit.value;
+    }
+    set(key, value) {
+        if (this.ttlMs <= 0)
+            return;
+        this.store.set(key, { expiresAt: Date.now() + this.ttlMs, value });
+    }
+}
+export class DashboardClient {
+    cfg;
+    /** 由服务端 Date 头估算的「服务端时间 - 本地时间」偏移（毫秒）。 */
+    skewMs = 0;
+    cache = new TtlCache(0);
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.cache = new TtlCache(cfg.TIMARAI_FILTER_CACHE_TTL_MS);
+    }
+    absoluteUrl(path) {
+        return new URL(DASHBOARD_ROUTE_PREFIX + path.replace(/^\/+/, ""), `${this.cfg.TIMARAI_API_BASE_URL}/`).toString();
+    }
+    nowWithSkew() {
+        return timestampMillis(new Date(Date.now() + this.skewMs));
+    }
+    audit(entry) {
+        const safe = JSON.stringify(entry, (_k, v) => typeof v === "string" ? redactSecret(v, this.cfg.TIMARAI_PLATFORM_SECRET) : v);
+        // STDIO 传输下 stdout 被协议占用，日志必须走 stderr。
+        process.stderr.write(`[TimarAI-Dashboard-MCP] ${safe}\n`);
+    }
+    async dispatch(spec, requestId, rawBody, signBody) {
+        const { headers } = buildSignedHeaders({
+            clientId: this.cfg.TIMARAI_PLATFORM_CLIENT_ID,
+            secret: this.cfg.TIMARAI_PLATFORM_SECRET,
+            requestId,
+            timestamp: this.nowWithSkew(),
+            rawBody: signBody,
+        });
+        const startedAt = Date.now();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.cfg.TIMARAI_HTTP_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(this.absoluteUrl(spec.path), {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...headers },
+                // rawBody 与签名串同源，禁止替换为对象让 fetch 重新序列化。
+                body: rawBody,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            const elapsedMs = Date.now() - startedAt;
+            const reason = controller.signal.aborted
+                ? `请求超时（${this.cfg.TIMARAI_HTTP_TIMEOUT_MS}ms）`
+                : `网络错误：${error.message}`;
+            this.audit({ event: "http_error", requestId, endpointId: spec.id, elapsedMs, reason });
+            throw new ApiError(reason, {
+                endpointId: spec.id,
+                requestId,
+                httpStatus: null,
+                code: null,
+                hint: "检查 TIMARAI_API_BASE_URL 连通性与防火墙策略。",
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const elapsedMs = Date.now() - startedAt;
+        const text = await response.text();
+        // 借用响应 Date 头持续校正时钟偏斜，避免每次都靠失败来纠偏。
+        const serverDate = response.headers.get("date");
+        if (serverDate) {
+            const parsed = Date.parse(serverDate);
+            if (!Number.isNaN(parsed))
+                this.skewMs = parsed - Date.now();
+        }
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                this.audit({ event: "bad_json", requestId, endpointId: spec.id, httpStatus: response.status });
+                throw new ApiError(`响应不是合法 JSON（HTTP ${response.status}）`, {
+                    endpointId: spec.id,
+                    requestId,
+                    httpStatus: response.status,
+                    code: null,
+                    hint: "确认请求是否命中了正确的 API Host（可能被网关返回了 HTML 错误页）。",
+                });
+            }
+        }
+        const env = unwrapEnvelope(payload);
+        const code = env.code === undefined || env.code === null ? null : String(env.code);
+        const msg = typeof env.msg === "string" ? env.msg : "";
+        if (code !== API_CODE.SUCCESS) {
+            const { hint } = describeFailure(code ?? "", msg);
+            this.audit({
+                event: "api_error",
+                requestId,
+                endpointId: spec.id,
+                httpStatus: response.status,
+                code,
+                msg,
+            });
+            throw new ApiError(`[${code ?? "unknown"}] ${msg || "调用失败"}`, {
+                endpointId: spec.id,
+                requestId,
+                httpStatus: response.status,
+                code,
+                hint,
+            });
+        }
+        this.audit({
+            event: "ok",
+            requestId,
+            endpointId: spec.id,
+            httpStatus: response.status,
+            elapsedMs,
+        });
+        return {
+            meta: {
+                endpointId: spec.id,
+                path: `${DASHBOARD_ROUTE_PREFIX}${spec.path}`,
+                requestId,
+                httpStatus: response.status,
+                elapsedMs,
+                code: API_CODE.SUCCESS,
+            },
+            data: env.data,
+        };
+    }
+    /**
+     * 调用一个驾驶舱路由。
+     *
+     * 失败策略：
+     * - `401 SignaturesNotMatch`：换用「空 body」签名串重试一次。
+     *   这是针对部分网关/中间件重读 body 失败、导致对端收到空串的兜底；
+     *   一旦命中会在 stderr 打出 WARN，便于定位这类链路问题。
+     * - `5xx`：按指数退避重试 `TIMARAI_MAX_RETRIES` 次。
+     */
+    async call(spec, body) {
+        const rawBody = JSON.stringify(body);
+        const requestId = randomUUID();
+        let attempt = 0;
+        let lastError = null;
+        const variants = [
+            { name: "sent-body", signBody: rawBody },
+            { name: "empty-body", signBody: undefined },
+        ];
+        for (const variant of variants) {
+            attempt += 1;
+            try {
+                return await this.dispatch(spec, requestId, rawBody, variant.signBody);
+            }
+            catch (error) {
+                if (!(error instanceof ApiError))
+                    throw error;
+                lastError = error;
+                if (error.detail.code === API_CODE.SIGNATURES_NOT_MATCH && variant.name === "sent-body") {
+                    this.audit({
+                        event: "warn",
+                        requestId,
+                        endpointId: spec.id,
+                        reason: "sent-body signature rejected, retry with empty-body variant",
+                    });
+                    continue;
+                }
+                const retryable = error.detail.httpStatus !== null &&
+                    error.detail.httpStatus >= 500 &&
+                    attempt <= this.cfg.TIMARAI_MAX_RETRIES + variants.length - 1;
+                if (retryable) {
+                    await new Promise((r) => setTimeout(r, 200 * 2 ** (attempt - 1)));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError ?? new ApiError("未知调用失败", {
+            endpointId: spec.id,
+            requestId,
+            httpStatus: null,
+            code: null,
+            hint: "请结合 requestId 排查。",
+        });
+    }
+    /** 带 TTL 缓存的调用（仅用于 filters）。 */
+    async callCached(spec, body, cacheKey) {
+        const cached = this.cache.get(cacheKey);
+        if (cached)
+            return cached;
+        const result = await this.call(spec, body);
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -0,0 +1,164 @@
+/**
+ * 运行时配置。
+ *
+ * 安全约束：
+ * 1. Secret 仅从环境变量读取，绝不写入日志、错误信息或工具返回结果。
+ * 2. 缺失必填项时快速失败，并给出「可行动」的修复指引，而不是抛出原始堆栈。
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+const Booleanish = z
+    .enum(["true", "false"])
+    .default("true")
+    .transform((v) => v === "true");
+const EnvSchema = z.object({
+    TIMARAI_API_BASE_URL: z.string().url(),
+    TIMARAI_PLATFORM_CLIENT_ID: z.string().min(1),
+    TIMARAI_PLATFORM_SECRET: z.string().min(8),
+    TIMARAI_HTTP_TIMEOUT_MS: z.coerce.number().int().positive().max(120_000).default(15_000),
+    /** 传输层重试次数（仅网络错误 / 5xx）。签名类失败由客户端单独做策略重试。 */
+    TIMARAI_MAX_RETRIES: z.coerce.number().int().min(0).max(3).default(1),
+    /** 服务端硬限制为 90 天；工具层前置校验以给出更友好的提示。 */
+    TIMARAI_MAX_DATE_SPAN_DAYS: z.coerce.number().int().positive().max(90).default(90),
+    /** 是否注册 call_endpoint 逃生阀工具。 */
+    TIMARAI_ALLOW_RAW_ENDPOINT: Booleanish,
+    /** 筛选项缓存时长（该数据变动极低频）。 */
+    TIMARAI_FILTER_CACHE_TTL_MS: z.coerce.number().int().nonnegative().default(300_000),
+    MCP_TRANSPORT: z.enum(["stdio", "http"]).default("stdio"),
+    /** HTTP 模式监听地址。默认只听回环；要给别人连就显式指定，并自行加反代鉴权。 */
+    MCP_HTTP_HOST: z.string().min(1).default("127.0.0.1"),
+    MCP_HTTP_PORT: z.coerce.number().int().positive().max(65_535).default(8899),
+    /** 图表 / 报表的落盘目录；相对路径按仓库根目录解析。 */
+    TIMARAI_OUTPUT_DIR: z.string().min(1).default("out"),
+});
+/**
+ * 极简 .env 加载器（零依赖）。生产环境建议由宿主进程直接注入环境变量。
+ *
+ * 对外导出是为了让 CLI 脚本与 Server 进程共用同一份加载逻辑，
+ * 避免脚本各自实现一套、导致两边读到的配置不一致。
+ * 已存在的环境变量优先（宿主注入 > .env）。
+ */
+export function loadDotEnvIfPresent() {
+    try {
+        const raw = readFileSync(new URL("../.env", import.meta.url), "utf8");
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eq = trimmed.indexOf("=");
+            if (eq <= 0)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            const value = trimmed.slice(eq + 1).trim();
+            if (process.env[key] === undefined)
+                process.env[key] = value;
+        }
+    }
+    catch {
+        // .env 不存在属正常情况
+    }
+}
+/** 命令行参数 → 环境变量。少数客户端不传 env，用 args 也能配。 */
+const CLI_FLAGS = {
+    url: "TIMARAI_API_BASE_URL",
+    key: "TIMARAI_PLATFORM_KEY",
+    "client-id": "TIMARAI_PLATFORM_CLIENT_ID",
+    secret: "TIMARAI_PLATFORM_SECRET",
+    out: "TIMARAI_OUTPUT_DIR",
+};
+export function applyCliOverrides(argv = process.argv.slice(2)) {
+    for (const arg of argv) {
+        const m = /^--([a-z-]+)=(.*)$/.exec(arg);
+        if (!m)
+            continue;
+        const flag = m[1];
+        const value = m[2];
+        if (!flag || value === undefined)
+            continue;
+        const envName = CLI_FLAGS[flag];
+        if (envName && value.trim())
+            process.env[envName] = value.trim();
+    }
+}
+/**
+ * 凭证归一。
+ *
+ * 主写法是分开的两项（ClientId + Secret）；也接受合并成一个
+ * `TIMARAI_PLATFORM_KEY=clientId:secret`——在客户端配置里一次粘完更省事。
+ * 分开写优先，两者都填时以分开写的为准。
+ */
+export function normalizeCredentials(env) {
+    const key = env.TIMARAI_PLATFORM_KEY?.trim();
+    if (!key)
+        return env;
+    const i = key.indexOf(":");
+    if (i <= 0 || i === key.length - 1) {
+        throw new ConfigError([
+            "TIMARAI_PLATFORM_KEY: 应为 clientId:secret（英文冒号分隔），例如 <你的 clientId>:<明文密钥>",
+        ]);
+    }
+    return {
+        ...env,
+        TIMARAI_PLATFORM_CLIENT_ID: env.TIMARAI_PLATFORM_CLIENT_ID || key.slice(0, i).trim(),
+        TIMARAI_PLATFORM_SECRET: env.TIMARAI_PLATFORM_SECRET || key.slice(i + 1).trim(),
+    };
+}
+/**
+ * 首次使用引导。
+ *
+ * STDIO 下 stdout 归协议所有、stdin 是 Agent 的 JSON-RPC，Server 不可能交互式提问。
+ * 所以这里只做一件事：**把要填什么、去哪拿说清楚**——
+ * 只列缺失项的话，第一次用的人连 ClientId 是什么都不知道。
+ */
+export function firstRunGuidance(issues) {
+    const missingKeys = issues.map((i) => i.split(":")[0]?.trim() ?? i);
+    const need = (key) => missingKeys.some((k) => k === key);
+    const lines = [
+        "尚未完成配置：需要「接口地址 + 平台凭证」才能工作。",
+        "",
+        "最快的方式：在 Agent 客户端的 MCP 配置里填这三个环境变量（**都没有默认值**，",
+        "地址和凭证按环境由平台侧给出，找平台管理员索取）：",
+        "",
+    ];
+    if (need("TIMARAI_API_BASE_URL")) {
+        lines.push("  TIMARAI_API_BASE_URL        —— 驾驶舱 OpenAPI 根地址，形如 https://<你的接口域名>");
+    }
+    if (need("TIMARAI_PLATFORM_CLIENT_ID")) {
+        lines.push("  TIMARAI_PLATFORM_CLIENT_ID  —— 平台数据字典里为该项 OpenAPI 登记的客户端标识");
+    }
+    if (need("TIMARAI_PLATFORM_SECRET")) {
+        lines.push("  TIMARAI_PLATFORM_SECRET     —— 与之配对的明文密钥（找平台管理员登记）");
+    }
+    lines.push("", "也可以合并成一个：TIMARAI_PLATFORM_KEY=<你的 clientId>:<明文密钥>", "（或写成命令行参数：--url=https://<你的接口域名> --key=<你的 clientId>:<明文密钥>）", "", "源码安装的用户另可：cp .env.example .env 手工填写，或运行 npm run setup 走向导。", "注意：.env 不要提交进版本库（.gitignore 已排除）。");
+    return lines.join("\n");
+}
+export class ConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super([
+            "配置校验失败，请检查 MCP 服务器环境变量：",
+            ...issues.map((i) => `  - ${i}`),
+            "",
+            "必填三项：TIMARAI_API_BASE_URL / TIMARAI_PLATFORM_CLIENT_ID / TIMARAI_PLATFORM_SECRET",
+            "（也可合并成一个 TIMARAI_PLATFORM_KEY=clientId:secret）",
+            "源码安装可运行：npm run setup；参考仓库根目录的 .env.example。",
+        ].join("\n"));
+        this.issues = issues;
+        this.name = "ConfigError";
+    }
+}
+export function loadConfig() {
+    loadDotEnvIfPresent();
+    const parsed = EnvSchema.safeParse(normalizeCredentials(process.env));
+    if (!parsed.success) {
+        throw new ConfigError(parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`));
+    }
+    return parsed.data;
+}
+/** 抹掉文本中可能出现的 Secret，用于安全输出到 stderr。 */
+export function redactSecret(input, secret) {
+    if (!secret)
+        return input;
+    return input.split(secret).join("***REDACTED***");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/date-range.js

@@ -0,0 +1,190 @@
+/**
+ * 日期范围解析。
+ *
+ * 重要：报表时区为固定的 \`Asia/Shanghai\`（服务端以此封板日统计），
+ * 因此「今天 / 昨天」必须按报表时区折算，而不是按 MCP 宿主机的本地时区。
+ * 这是驾驶舱口径一致性的常见踩坑点。
+ */
+export const REPORT_TIME_ZONE = "Asia/Shanghai";
+/** 与需求文档「全局筛选区-时间」下拉框一致：今日/昨日/本周/本月/近7天/近30天/近90天。 */
+export const DATE_PRESETS = [
+    "today",
+    "yesterday",
+    "last_7d",
+    "last_30d",
+    "last_90d",
+    "this_week",
+    "last_week",
+    "this_month",
+    "last_month",
+];
+export class DateRangeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DateRangeError";
+    }
+}
+/** 取报表时区下的今天（YYYY-MM-DD）。 */
+export function todayInReportTz(now = new Date()) {
+    const fmt = new Intl.DateTimeFormat("en-CA", {
+        timeZone: REPORT_TIME_ZONE,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    });
+    return fmt.format(now);
+}
+const STAT_DATE_FMT = new Intl.DateTimeFormat("en-CA", {
+    timeZone: REPORT_TIME_ZONE,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+});
+/**
+ * 归一化「统计日」标签。
+ *
+ * 序列里的日期字段给过不止一种写法：`"2026-09-12"` 字符串、Unix 秒、Unix 毫秒。
+ * 只认字符串的话，遇到时间戳就会得到一串空标签——图还在，但读不出是哪天，
+ * 而且这种错不会报错，只会产出一张「看不懂但看着正常」的图。
+ * 这里三种写法都认，统一输出 YYYY-MM-DD（按报表时区，与封板口径一致）。
+ */
+export function statDateLabel(value) {
+    if (typeof value === "string") {
+        if (/^\d{10,13}$/.test(value))
+            return fromTimestamp(Number(value));
+        return value.slice(0, 10);
+    }
+    if (typeof value === "number" && Number.isFinite(value))
+        return fromTimestamp(value);
+    return "";
+}
+/** 阈值取 1e11：它两边分别落在「秒」与「毫秒」的合理区间内，足以区分两种单位。 */
+function fromTimestamp(value) {
+    const ms = value < 1e11 ? value * 1000 : value;
+    const date = new Date(ms);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return STAT_DATE_FMT.format(date).replace(/\//g, "-").slice(0, 10);
+}
+/**
+ * 与当前区间**等长且紧邻其前**的对照区间，用于算环比。
+ * 例：2026-09-01~09-07（7 天）→ 2026-08-25~08-31。
+ * 报表口径按天聚合，用 UTC 日界即可，不必再折算时区。
+ */
+export function previousPeriod(startDate, endDate) {
+    const start = new Date(`${startDate}T00:00:00Z`);
+    const end = new Date(`${endDate}T00:00:00Z`);
+    const spanDays = Math.max(1, Math.round((end.getTime() - start.getTime()) / 86_400_000) + 1);
+    const prevEnd = new Date(start.getTime() - 86_400_000);
+    const prevStart = new Date(prevEnd.getTime() - (spanDays - 1) * 86_400_000);
+    return {
+        startDate: prevStart.toISOString().slice(0, 10),
+        endDate: prevEnd.toISOString().slice(0, 10),
+    };
+}
+function parseIsoDate(value, field) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new DateRangeError(`${field} 必须为 YYYY-MM-DD 格式，收到：${value}`);
+    }
+    const date = new Date(`${value}T00:00:00Z`);
+    if (Number.isNaN(date.getTime())) {
+        throw new DateRangeError(`${field} 不是合法日期：${value}`);
+    }
+    return value;
+}
+function addDays(isoDate, days) {
+    const base = new Date(`${isoDate}T00:00:00Z`);
+    base.setUTCDate(base.getUTCDate() + days);
+    return base.toISOString().slice(0, 10);
+}
+function startOfMonth(isoDate) {
+    return `${isoDate.slice(0, 7)}-01`;
+}
+function endOfPreviousMonth(isoDate) {
+    const firstOfMonth = new Date(`${startOfMonth(isoDate)}T00:00:00Z`);
+    firstOfMonth.setUTCDate(0);
+    return firstOfMonth.toISOString().slice(0, 10);
+}
+/** 周一为一周起始，与国内报表习惯一致。 */
+function startOfWeek(isoDate) {
+    const base = new Date(`${isoDate}T00:00:00Z`);
+    const dayOfWeek = base.getUTCDay(); // 0=周日
+    const offset = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
+    base.setUTCDate(base.getUTCDate() + offset);
+    return base.toISOString().slice(0, 10);
+}
+function inclusiveSpan(startDate, endDate) {
+    const start = Date.parse(`${startDate}T00:00:00Z`);
+    const end = Date.parse(`${endDate}T00:00:00Z`);
+    return Math.floor((end - start) / 86_400_000) + 1;
+}
+export function resolveDateRange(options) {
+    const now = options.now ?? new Date();
+    const today = todayInReportTz(now);
+    let startDate;
+    let endDate;
+    let resolvedFrom;
+    if (options.startDate || options.endDate) {
+        startDate = parseIsoDate(options.startDate ?? options.endDate, "startDate");
+        endDate = parseIsoDate(options.endDate ?? options.startDate, "endDate");
+        resolvedFrom = "explicit";
+    }
+    else {
+        const preset = options.preset ?? "last_7d";
+        resolvedFrom = `preset:${preset}`;
+        switch (preset) {
+            case "today":
+                startDate = today;
+                endDate = today;
+                break;
+            case "yesterday":
+                startDate = addDays(today, -1);
+                endDate = startDate;
+                break;
+            case "last_7d":
+                endDate = today;
+                startDate = addDays(today, -6);
+                break;
+            case "last_30d":
+                endDate = today;
+                startDate = addDays(today, -29);
+                break;
+            case "last_90d":
+                endDate = today;
+                startDate = addDays(today, -89);
+                break;
+            case "this_week":
+                startDate = startOfWeek(today);
+                endDate = today;
+                break;
+            case "last_week": {
+                const thisWeekStart = startOfWeek(today);
+                endDate = addDays(thisWeekStart, -1);
+                startDate = addDays(endDate, -6);
+                break;
+            }
+            case "this_month":
+                startDate = startOfMonth(today);
+                endDate = today;
+                break;
+            case "last_month": {
+                endDate = endOfPreviousMonth(today);
+                startDate = startOfMonth(endDate);
+                break;
+            }
+            default: {
+                const exhaustive = preset;
+                throw new DateRangeError(`不支持的日期预设：${String(exhaustive)}`);
+            }
+        }
+    }
+    if (startDate > endDate) {
+        throw new DateRangeError(`开始日期 ${startDate} 不能晚于结束日期 ${endDate}。`);
+    }
+    const spanDays = inclusiveSpan(startDate, endDate);
+    if (spanDays > options.maxSpanDays) {
+        throw new DateRangeError(`查询跨度 ${spanDays} 天超过上限 ${options.maxSpanDays} 天（接口最大支持 90 天）。请缩短日期范围，或按周分段查询后自行汇总。`);
+    }
+    return { startDate, endDate, spanDays, resolvedFrom };
+}
+//# sourceMappingURL=date-range.js.map