gangtise-openapi-cli 0.30.1 → 0.32.0

package/dist/src/core/args.js

@@ -288,6 +288,100 @@ const SCREENER_FIELD = /^F[1-9][0-9]*$/;
  * `contains 'F2 系列'` operand is not mistaken for a reference. */
 const SCREENER_FIELD_REF = /\bF[1-9][0-9]*\b/g;
 const SCREENER_STRING_LITERAL = /'[^']*'|"[^"]*"/g;
+/** Split an expression into `(`, `)`, `&&`, `||` and the atoms between them.
+ * String literals are copied verbatim so a `||` or an `F2` inside one is never
+ * mistaken for syntax. */
+function tokenizeScreenerExpression(src) {
+    const tokens = [];
+    let atom = "";
+    const flush = () => {
+        if (atom.trim())
+            tokens.push(atom);
+        atom = "";
+    };
+    for (let i = 0; i < src.length;) {
+        const ch = src[i];
+        if (ch === "'" || ch === '"') {
+            const close = src.indexOf(ch, i + 1);
+            const stop = close === -1 ? src.length : close + 1;
+            atom += src.slice(i, stop);
+            i = stop;
+        }
+        else if (src.startsWith("&&", i) || src.startsWith("||", i)) {
+            flush();
+            tokens.push(src.slice(i, i + 2));
+            i += 2;
+        }
+        else if (ch === "(" || ch === ")") {
+            flush();
+            tokens.push(ch);
+            i += 1;
+        }
+        else {
+            atom += ch;
+            i += 1;
+        }
+    }
+    flush();
+    return tokens;
+}
+/** Whether the expression still has a path that could have been evaluated, given
+ * the variables the response actually returned a column for.
+ *
+ * The boolean structure decides, not the mere presence of a `||`:
+ *   - a term is evaluable when every variable it names has a column;
+ *   - `A && B` needs BOTH sides — a missing mandatory conjunct is an unprovable
+ *     claim even if the other side is a disjunction;
+ *   - `A || B` needs only one — a row can legitimately match through one operand
+ *     while the other is not evaluable at all (probed 2026-08-03: `F1 > 0 || F2
+ *     > 0` over 09992.HK, where `finc_pe_ttm` has no HK coverage, matches on F2).
+ *
+ * So `F1 && (F2 || F3)` missing F1, and `F1 || F2` missing both, are both
+ * unevaluable and must fail — checking only for a `||` anywhere would let them
+ * through. */
+export function screenerExpressionIsEvaluable(expression, present) {
+    const tokens = tokenizeScreenerExpression(expression ?? "");
+    let pos = 0;
+    const unit = () => {
+        if (tokens[pos] === "(") {
+            pos += 1;
+            const value = or();
+            if (tokens[pos] === ")")
+                pos += 1;
+            return value;
+        }
+        const atom = tokens[pos++] ?? "";
+        // A term naming no variable (a literal comparison) is always evaluable.
+        return (atom.replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? []).every((ref) => present.has(ref));
+    };
+    const and = () => {
+        let value = unit();
+        // Evaluate both sides before combining: short-circuiting would leave the
+        // parser mid-expression.
+        while (tokens[pos] === "&&") {
+            pos += 1;
+            const right = unit();
+            value = value && right;
+        }
+        return value;
+    };
+    const or = () => {
+        let value = and();
+        while (tokens[pos] === "||") {
+            pos += 1;
+            const right = and();
+            value = value || right;
+        }
+        return value;
+    };
+    return or();
+}
+/** Variables the expression actually filters on, string literals stripped. These
+ * are the bindings whose VALUES the result depends on — a column missing for one
+ * of them means the filter cannot be shown to have been applied. */
+export function screenerExpressionFields(expression) {
+    return (expression ?? "").replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? [];
+}
 // Parse the screener's `--indicator "F1:code"` bindings and merge each one's
 // `--indicator-param "F1:key=value"` specs. Params key off the variable, not the
 // code, because the same indicator may legitimately appear under two variables
@@ -320,26 +414,10 @@ export function parseScreenerIndicators(bindings, paramSpecs, expression) {
     // The server does reject this (100003), but only after a round trip — and the
     // symmetric mistake (binding a variable the expression never uses) it accepts
     // silently while still billing the extra column.
-    for (const ref of (expression ?? "").replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? []) {
+    for (const ref of screenerExpressionFields(expression)) {
         if (!indicators.has(ref)) {
             throw new ValidationError(`--expression references "${ref}", which no --indicator binds`);
         }
     }
     return [...indicators.values()];
 }
-/** Indicator codes bound to more than one screener variable, in first-seen
- * order. The API is specified to allow this (one code under two variables with
- * different parameters), but the server currently answers such a request with an
- * empty result set — probed 2026-08-02. Callers warn rather than reject: the
- * capability is intended and a server-side fix is in flight, so a hard block
- * here would have to be reverted. */
-export function duplicateScreenerCodes(indicators) {
-    const seen = new Set();
-    const duplicated = new Set();
-    for (const { indicatorCode } of indicators) {
-        if (seen.has(indicatorCode))
-            duplicated.add(indicatorCode);
-        seen.add(indicatorCode);
-    }
-    return [...duplicated];
-}

package/dist/src/core/client.js

@@ -427,8 +427,9 @@ export class GangtiseClient {
             },
         }).catch((error) => {
             // Until 2026-08-01 EDE answered a no-data query with 999999, so this hint
-            // led with "多为查询无数据". No-data now comes back as an empty array, which
-            // leaves 999999 meaning an actual server fault — but the parameter checklist
+            // led with "多为查询无数据". No-data now comes back as a null CELL with its
+            // row and column intact (re-probed 2026-08-08), which leaves 999999 meaning
+            // an actual server fault — but the parameter checklist
             // is still the right first move, because a wrong param name or date axis
             // silently yields an EMPTY TABLE rather than this error. Only the data
             // endpoints take a date/security/params; indicator.search shares the
@@ -436,7 +437,7 @@ export class GangtiseClient {
             // instead of nonsensical date/scope/param guidance.
             const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series' || endpoint.key === 'indicator.screener';
             if (isIndicatorFetch && error instanceof ApiError && error.code === '999999') {
-                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名是静默失效）、日期匹配指标周期（财务/MRQ 用报告期末如 2025-12-31、日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意「查询无数据」现在返回空表而不是此码。');
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名是静默失效）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意此码不表示无数据——有效 code 无数据现在返回保留行列的 null 单元格，空表则多半是整个轴的 code 都没被识别。');
             }
             throw error;
         });

package/dist/src/core/commandBodies.js

@@ -36,12 +36,17 @@ export function buildStockPoolStocksBody(options) {
 }
 /** Parameter keys that REPLACE an indicator's `tradeDate`. The 2026-08-01 EDE
  * revision dropped the root-level `date`, so `--date` now fans out into each
- * indicator's `tradeDate`. Report-period indicators read `reportDate` instead
- * and answer a `tradeDate` with an EMPTY result rather than an error (probed
- * 2026-08-01 on `is_op_rev_mom`), so a caller-supplied `reportDate` suppresses
- * the injection for that indicator. Injecting into an indicator that takes no
- * date at all is harmless — `pty_op_scope` still answers normally with a stray
- * `tradeDate` attached.
+ * indicator's `tradeDate`. A caller-supplied `reportDate` suppresses that
+ * injection for its indicator, so the two date fields are never sent together.
+ *
+ * This used to be load-bearing in a stronger sense: a report-period indicator
+ * answered a `tradeDate` with an EMPTY result rather than an error (probed
+ * 2026-08-01 on `is_op_rev_mom`). Re-probed 2026-08-08 — the server now resolves
+ * a `tradeDate` to the enclosing report period, and `is_op_rev_mom` returns the
+ * same 33.4903 either way. Kept regardless: sending the caller's own date field
+ * rather than a second one alongside it is the honest request, and it survives a
+ * rollback. Injecting into an indicator that takes no date at all is harmless —
+ * `pty_op_scope` still answers normally with a stray `tradeDate` attached.
  *
  * `sDate` is deliberately NOT here. It is an interval START, not a substitute:
  * `qte_vol_intvl` declares `tradeDate` required (the interval END) and `sDate`
@@ -92,11 +97,15 @@ export function buildIndicatorScreenerBody(options) {
         universe: maybeArray(options.security),
         expression: options.expression,
         // Every indicator gets a date, including ones whose parameterList is empty.
-        // That is not just convenience: the screener drops any indicator sent with
-        // `parameters: []` — probed 2026-08-02, `pty_op_scope` + `F1 contains '酒'`
-        // matches nothing with an empty list and correctly returns 五粮液/贵州茅台
-        // with a (for that indicator meaningless) tradeDate attached. The official
-        // doc's own `F3 contains '酒'` example cannot work as written.
+        // Harmless there (a parameterless indicator answers normally with a stray
+        // tradeDate), and it keeps one rule for the whole list rather than a
+        // per-indicator exception.
+        //
+        // It also used to be load-bearing: through 2026-08-02 the screener DROPPED
+        // any indicator sent with `parameters: []`, so the official doc's own
+        // `F3 contains '酒'` example could not work as written. Re-probed 2026-08-03:
+        // fixed server-side. Kept anyway — unconditional is simpler than conditional,
+        // and it survives a rollback.
         indicatorList: indicators.map((indicator) => (indicator.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))
             ? indicator
             : { ...indicator, parameters: [...indicator.parameters, { paramKey: "tradeDate", paramValue: options.date }] })),

package/dist/src/core/endpoints.js

@@ -49,6 +49,24 @@ const ENDPOINT_DEFS = {
         // 50/篇 — same price tier as the AI Agent calls; billing probed non-idempotent.
         retry: "no-replay",
     },
+    "insight.pamirs-summary.list": {
+        method: "POST",
+        path: "/application/open-insight/pamirs-summary/getList",
+        kind: "json",
+        description: "List Pamirs expert summaries (requires the expert-summary database)",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.pamirs-summary.download": {
+        method: "GET",
+        path: "/application/open-insight/pamirs-summary/download/file",
+        kind: "download",
+        description: "Download a Pamirs expert summary file",
+        // The 2026-08-07 spec states an entitlement (the expert-summary database) but
+        // no per-call price. Treated as non-idempotent anyway, like its
+        // `insight.summary.download` sibling: if it does meter, a 5xx replay
+        // double-bills, and the only cost of being wrong is losing one retry.
+        retry: "no-replay",
+    },
     "insight.roadshow.list": {
         method: "POST",
         path: "/application/open-insight/schedule/roadshow/getList",

package/dist/src/core/errors.js

@@ -72,7 +72,9 @@ const ERROR_HINTS = {
     // --report-date 的用户越导越错。
     "110001": "看参数名：`--*-date` 用 YYYY-MM-DD，`--*-time` 用 \"YYYY-MM-DD HH:mm:ss\"（`ai knowledge-batch` 的 --start-time/--end-time 收时间戳或 datetime，CLI 统一转 13 位毫秒）。",
     "110002": "起始晚于结束——检查 --start-date/--end-date 或 --start-time/--end-time 的先后。",
-    "110003": "缩短查询窗口后重试。",
+    // 超出的是账号数据权限的时间下界，不是单次窗口太宽——`--fiscal-year 2015` 这种
+    // 整个区间都在界外的请求，怎么缩窗口都还是这个码（实测 2026-08-08）。
+    "110003": "查询时间超出本账号的数据权限范围——把日期移进范围内（整个区间都早于下界时缩短窗口无用），或联系客户经理开通更长历史。",
     "120001": "用 `gangtise reference securities-search` 确认代码与后缀（如 600519.SH / 00700.HK）。",
     "130001": "未找到数据——先核对查询条件；EDE 指标端点此码也可能是未开通该指标权限，仍失败联系客户经理。",
     "130002": "确认下载 ID 有效且本账号可见；下载类还需检查 --file-type 取值是否合法（非法 file-type 也归此码）。",
@@ -91,6 +93,9 @@ const ERROR_HINTS = {
     "210001": "换一篇，或改用 list 取正文摘要。",
     "220001": "改用 list 取正文摘要。",
     "230001": "只有自己上传的文件可下载。",
+    // 2026-08-07 新增码。私域模块，`vault wechat-*` 就在这个模块下且明确要求
+    // 「已绑定并激活群消息助理」，所以本 CLI 够得着，不能当作不可达而不给提示。
+    "230002": "微信账号未绑定——群消息类接口要求先在 Gangtise 端绑定并激活群消息助理、且助理已入群。",
     "240001": "换更早的 --period（如 2025q3 → 2025interim）。",
     "240002": "改述后重新提交。",
     "240003": "对照命令 --help 检查取值。",
@@ -130,8 +135,10 @@ export class ApiError extends CliError {
     /** Server-specified Retry-After (ms), set on 429 responses so the transport
      * backoff can honor it instead of the default exponential schedule. */
     retryAfterMs, 
-    /** Context-specific hint that beats the generic per-code table — e.g. EDE's
-     * 999999 means "no data", not the table's "系统错误，请稍后重试". */
+    /** Context-specific hint that beats the generic per-code table — e.g. the
+     * EDE fetch endpoints replace 999999's generic "系统错误，请稍后重试" with a
+     * parameter checklist, because a wrong param name or date axis there yields
+     * an empty TABLE rather than this code. */
     hintOverride) {
         super(message);
         this.code = code;