ozon-seller-mcp 2.3.0 → 2.3.1

package/README.md

@@ -122,6 +122,8 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 \* 2026-10-26 在一家约 480 个商品的店铺实测，从国内网络访问。
 
+营收 `revenue`（来自 `/v1/analytics/data`）单位是卢布，结果里带 `revenue_currency: "RUB"`；商品价格 `price`/`old_price`/`min_price` 是店铺结算币种（可能是 CNY），见 `price_currency`（旧字段 `currency` 保留，值相同）。两者不要直接相加或相除。
+
 ### 通用工具
 
 | 工具 | 用途 |
@@ -158,7 +160,7 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 | `ozon_ads_api_catalog` | 搜索全部 48 个广告接口 + 官方说明中给出的 12 个 `/json` 报表版本，或查看单个接口的参数与响应定义 |
 | `ozon_ads_api_call` | 按路径调用任一广告接口：路径参数和查询参数放 `params`，请求体放 `body` |
 
-- `ozon_ads_stats` 的活动汇总来自 `/api/client/statistics/campaign/product/json`（同步，不消耗限额）；商品明细来自异步活动报表 `/api/client/statistics/json`（每次最多 10 个活动，同一账号同时只生成 1 个，最多等 90 秒），包含本期内已移出活动的商品。`include_products=false` 只看活动汇总
+- `ozon_ads_stats` 的活动汇总来自 `/api/client/statistics/campaign/product/json`（同步，不消耗限额）；商品明细来自异步活动报表 `/api/client/statistics/json`（每次最多 10 个活动，同一账号同时只生成 1 个，最多等 90 秒），包含本期内已移出活动的商品。同一进程内同一广告账号的报表逐个生成：本服务记住每个广告账号最近提交的报表（UUID、提交时间），下一次提交前（`ozon_ads_stats` 和 `ozon_ads_api_call` 的报表提交，含外部流量报表）先在本次调用内查它的状态，等到 OK/ERROR（外部流量报表还有 TIMEOUT/CANCEL）或它已提交满 120 秒；查询失败不算完成，每次查询也受上一份报表剩余的等待上限约束。本次调用的时间预算内没等到就不提交并返回提示。报表提交不自动重试；已发出但结果未知（连接中断、超时、5xx）时，按“可能正在生成”处理，下一次提交等它满 120 秒。没有任何后台任务；相同查询同时进行时共用一份报表。`ozon_ads_stats` 整次调用（活动列表、汇总、取令牌、等待、重试、报表）共用一个 90 秒期限，超时即取消，不再发出后续请求。`include_products=false` 只看活动汇总
 - `/api/client/statistics/products/sku` 实测只接受今天或昨天（Ozon 返回 `date range must contain only today or yesterday`），所以不用于多天统计
 - `OZON_READ_ONLY=true` 时，改出价、启停活动、增删商品、开关“按订单付款”等 16 个写接口在发送前拦截（包括 `GET /api/client/campaign/all_sku_promo/activate` 这类用 GET 做写操作的接口）
 - 官方限制：每天总计 100 000 次；统计报表同一账号同时只能生成 1 个、一次最多 10 个活动、最长 62 天
@@ -185,13 +187,14 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 其他接口文档未写具体数字，Ozon 仍可能返回 429。
 
-本地保护：同一进程内超出上述窗口时直接返回“约 N 秒后可再调用”，不发请求；限流接口的相同只读请求 5 分钟内返回缓存（`from_cache: true`）。本地计数只统计当前进程（含被 Ozon 拒绝的调用），以 Ozon 服务端为准。只读请求遇到 429/502/503/504 且 `Retry-After` ≤ 5 秒时重试一次；写请求从不自动重试。
+本地保护：同一进程内超出上述窗口时直接返回“约 N 秒后可再调用”，不发请求；限流接口的相同只读请求 5 分钟内返回缓存（`from_cache: true`）。本地计数只统计当前进程（含被 Ozon 拒绝的调用），以 Ozon 服务端为准。只读请求遇到 429/502/503/504 且 `Retry-After`（秒数或 HTTP 日期）≤ 5 秒时重试一次；每次实际发送（含重试、等过冷却之后）在发出前一刻计入上述窗口，并受每个账号的重试额度限制（并发失败时不会把请求量翻倍），等待时间加少量随机抖动。写请求从不自动重试。Ozon 返回 429 后，同一账号（同一 Client-Id 或广告 Client ID）的后续请求都先等过 `Retry-After`（最多按 60 秒计）：剩余不超过 5 秒就等待后发送，更长则直接返回“约 N 秒后可再调用”；有独立限额的接口（上表）只冷却该接口本身。
 
 **实测注意**：`/v1/analytics/data` 带 `sort` 参数的请求在 2026-10-26 连续被 Ozon 以“每秒限流”拒绝，同样的请求不带 `sort` 正常。`ozon_top_products` 因此不传 `sort`，一次取 1000 个 SKU 后本地排序。
 
 ## 参数校验
 
-- 必填、类型、嵌套、枚举、上下限、数组约束、日期与 int32/int64/uint64 格式、未知字段，发送前全部校验
+- 必填、类型、嵌套、枚举、上下限、数组约束、日期、date-time（RFC 3339，须带时区，如 `2026-10-01T00:00:00Z`；闰秒只接受 UTC 23:59:60）与 int32/int64/uint64 格式、未知字段，发送前全部校验。少数字段（如 `/v1/finance/balance` 的 `date_from`）规范类型是 date-time、说明和官方示例却是 `YYYY-MM-DD`，这些字段两种写法都接受
+- 整数参数超出 ±9007199254740991 时直接拒绝：JSON 解析时这类数字已被舍入（9007199254740993 会变成 …992），照发可能作用到别的对象
 - 482 个 schema 与原 Python 版逐个比对一致（3114 个校验用例结论相同），以下 8 处除外
 - 官方规范有 8 个 schema 把某字段列为必填、却没有定义该字段（如 `/v2/products/stocks` 的 `quant_size`，`/v1/cargoes/label/transport/status` 的 `operation_idd`），原实现因此无法调用这些接口。现在这些字段改为“已声明、不校验类型”的可选字段，说明里注明官方列为必填，最终以 Ozon 返回为准
 - 官方 `type=null` 的字段禁止传入，不猜测类型；`int`/`bool` 等书写错误按无歧义方式规范化

package/bin/ozon-seller-mcp.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // MCP stdio entry. stdout carries JSON-RPC only; diagnostics go to stderr.
+import { redactText } from '../src/privacy.js';
 import { VERSION } from '../src/version.js';
 
 const args = process.argv.slice(2);
@@ -29,14 +30,15 @@ if (args.includes('--version') || args.includes('-v')) {
 `);
 } else {
   // A stray error must not kill the server mid-conversation; log it to stderr and keep serving.
-  const report = (kind) => (error) => process.stderr.write(`[ozon-seller-mcp] ${kind}: ${error?.stack ?? error}\n`);
+  // Logged text goes through the same redaction as tool results (configured keys, ad tokens).
+  const report = (kind) => (error) => process.stderr.write(`[ozon-seller-mcp] ${kind}: ${redactText(error)}\n`);
   process.on('unhandledRejection', report('unhandledRejection'));
   process.on('uncaughtException', report('uncaughtException'));
   try {
     const { main } = await import('../src/server.js');
     await main();
   } catch (error) {
-    process.stderr.write(`[ozon-seller-mcp] 启动失败：${error?.message ?? error}\n`);
+    process.stderr.write(`[ozon-seller-mcp] 启动失败：${redactText(error?.message ?? error)}\n`);
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozon-seller-mcp",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Ozon Seller API + Performance (ads) API MCP server: 482 seller endpoints, 48 advertising endpoints, one-call composite queries, read-only by default, strict schema validation.",
   "keywords": [
     "mcp",

package/src/ads/http.js

@@ -1,22 +1,32 @@
 // Performance API transport: client-credentials token, path/query parameters, JSON or CSV responses.
 // Shares the proxy setting and socket pool with the Seller API transport.
 import { OzonError, ValidationError } from '../errors.js';
-import { currentFetch, describeNetworkError, getDispatcher, parseJson, readCapped, sleep } from '../http.js';
-import { redact } from '../privacy.js';
+import {
+  RETRY_STATUSES, WRITE_UNKNOWN, currentFetch, describeNetworkError, discardBody, getDispatcher, parseJson, readErrorText, readResponse,
+  sleep,
+} from '../http.js';
+import { forgetTokens, holdToken, redact, rememberToken } from '../privacy.js';
+import {
+  DEFAULT_RETRY_MS, MAX_RETRY_WAIT_MS, admitRetry, admitSend, awaitCooldown, checkAdmission, noteRateLimited, parseRetryAfter,
+  withJitter,
+} from '../ratelimit.js';
 import { enforceMode } from '../schema.js';
 import { currentShop, hasAds, shops } from '../shops.js';
 import { VERSION } from '../version.js';
 import { parseCsv } from './csv.js';
 import { SAFE_PATH_VALUE, pathParamNames, validateAdsRequest } from './schema.js';
-import { ADS_BASE_URL, findAdsOperation } from './spec.js';
+import { ADS_BASE_URL, findAdsOperation, isReportSubmit } from './spec.js';
 
 const HOST = new URL(ADS_BASE_URL).host;
 const TOKEN_PATH = '/api/client/token';
+const TOKEN_OP = Object.freeze({ path: TOKEN_PATH });
 const USER_AGENT = `Ozon-Seller-MCP/${VERSION}`;
 const TOKEN_MARGIN_MS = 60_000;
 const DEFAULT_TOKEN_TTL_MS = 30 * 60_000;
 const MAX_BODY = 2_000_000;
-const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+// A token request serves every caller of the account, so no single caller's budget cancels it;
+// it has its own limit instead.
+const TOKEN_TIMEOUT_MS = 30_000;
 const SAFE_SEGMENT = new RegExp(SAFE_PATH_VALUE);
 
 export const CREDENTIAL_HELP = '在卖家后台 设置 → API 密钥 → Performance API 创建服务账号并添加密钥，'
@@ -30,6 +40,7 @@ const pendingTokens = new Map();
 export function resetAdsToken() {
   cachedTokens.clear();
   pendingTokens.clear();
+  forgetTokens();
 }
 
 // True when any shop has Performance API credentials (the ads tools are listed then).
@@ -46,44 +57,109 @@ function adsCredentials() {
   return { clientId: shop.perfClientId, secret: shop.perfSecret, shop };
 }
 
-// Bearer tokens are credentials too: hide the one a request used as well as every cached one.
-function hideTokens(text, ...tokens) {
-  const cached = [...cachedTokens.values()].map((t) => t.value);
-  return [...tokens, ...cached].filter(Boolean).reduce((out, token) => out.replaceAll(token, '[已隐藏令牌]'), String(text));
+// Rate-limit scope of a Performance account: its 429 cooldown and retry budget are its own,
+// separate from the Seller account of the same shop.
+const accountScope = (clientId) => `perf:${clientId}`;
+
+// The Performance client of the shop this call runs as. Not a secret (ozon_status shows it).
+export const adsAccount = () => adsCredentials().clientId;
+
+// A time limit for one call: `signal` aborts after `ms`. The timer never keeps the process alive
+// on its own (unref) and done() clears it once the work has settled.
+export function timeLimit(ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  timer.unref?.();
+  return { signal: controller.signal, deadline: Date.now() + ms, done: () => clearTimeout(timer) };
 }
 
-function scrubTokens(data, token) {
-  const text = JSON.stringify(data);
-  const hidden = hideTokens(text, token);
-  return hidden === text ? data : JSON.parse(hidden);
+const NOT_SENT = '已超过本次调用的时间预算，请求未发送。';
+const notSent = () => new OzonError(NOT_SENT);
+
+// Marks a failure of a request's own exchange, after it went out, without a definite answer from
+// Ozon: a network error or cancellation during the fetch, an unreadable success body, or a 5xx. Such
+// a request may have been carried out (e.g. a report may be being built). Failures before it was
+// sent (budget, cooldown, the token phase) and definite refusals (3xx, 4xx) carry no mark.
+const outcomeUnknown = (error) => Object.assign(error, { outcomeUnknown: true });
+// send() tags failures of the fetch itself; only execute() turns that into outcomeUnknown, for the
+// request it was asked to make. A token request's network error never marks a report submission.
+const fetchFailed = (error) => Object.assign(error, { fetchFailed: true });
+
+// Settles like `promise`, or rejects once `signal` aborts, whichever comes first: a request, a body
+// or a wait that hangs cannot outlive its caller's time budget, whatever the fetch implementation
+// does. A rejection of `promise` after the race was lost is handled here, never left unhandled.
+export function untilAborted(promise, signal, message = NOT_SENT) {
+  const raced = Promise.resolve(promise);
+  if (!signal) return raced;
+  raced.catch(() => {});
+  if (signal.aborted) return Promise.reject(new OzonError(message));
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new OzonError(message));
+    signal.addEventListener('abort', abort, { once: true });
+    raced.then((value) => {
+      signal.removeEventListener('abort', abort);
+      if (signal.aborted) abort();
+      else resolve(value);
+    }, (error) => {
+      signal.removeEventListener('abort', abort);
+      reject(error);
+    });
+  });
 }
 
-async function send(url, init, agent, { write = false } = {}) {
+// Every send waits out the account's shared 429 cooldown, then, right before it goes out, is
+// dropped if the caller's budget is used up, or checked and counted by the limiter. Bearer tokens
+// in a failure message are hidden by redact(), which knows every token issued in this process.
+async function send(url, init, agent, { write = false, scope, op, signal } = {}) {
+  try {
+    await awaitCooldown(op, scope, signal);
+  } catch (error) {
+    throw signal?.aborted ? notSent() : error;
+  }
+  if (signal?.aborted) throw notSent();
+  admitSend(op, Date.now(), scope);
   const sentAt = performance.now();
   try {
-    return await currentFetch()(url, { ...init, redirect: 'manual', dispatcher: agent });
+    return await untilAborted(currentFetch()(url, { ...init, redirect: 'manual', dispatcher: agent, signal }), signal);
   } catch (error) {
-    throw new OzonError(describeNetworkError(error, performance.now() - sentAt, HOST)
-      + (write ? ' 写入结果未知，请先查询业务状态，不要自动重试。' : ''));
+    if (signal?.aborted) throw fetchFailed(new OzonError(`等待 Ozon 响应超时，已取消请求。${write ? WRITE_UNKNOWN : ''}`));
+    throw fetchFailed(new OzonError(describeNetworkError(error, performance.now() - sentAt, HOST) + (write ? WRITE_UNKNOWN : '')));
   }
 }
 
-async function rejectRedirect(response, path) {
+function rejectRedirect(response, path) {
   if (response.status >= 300 && response.status < 400) {
-    await response.body?.cancel().catch(() => {});
+    discardBody(response);
     throw new OzonError(`HTTP ${response.status} ${path}：Ozon 返回重定向，为保护凭证未跟随。`);
   }
 }
 
-const errorText = async (response, token) => hideTokens(redact((await response.text().catch(() => '')).slice(0, 2000)), token);
+const errorText = (response, write = false) => readErrorText(response, write, 2000);
 
-async function requestToken({ clientId, secret, shop }, agent) {
+async function requestToken(credentials, agent) {
+  const limit = timeLimit(TOKEN_TIMEOUT_MS);
+  try {
+    return await untilAborted(fetchToken(credentials, agent, limit.signal), limit.signal, 'Performance API 授权请求超时，已取消。');
+  } finally {
+    limit.done();
+  }
+}
+
+async function fetchToken({ clientId, secret, shop }, agent, signal) {
+  const scope = accountScope(clientId);
   const response = await send(ADS_BASE_URL + TOKEN_PATH, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': USER_AGENT },
     body: JSON.stringify({ client_id: clientId, client_secret: secret, grant_type: 'client_credentials' }),
-  }, agent);
+  }, agent, { scope, op: TOKEN_OP, signal });
   await rejectRedirect(response, TOKEN_PATH);
+  if (response.status === 429) {
+    // The token endpoint shares the account's cooldown: every caller waits instead of asking again.
+    const delay = parseRetryAfter(response.headers.get('retry-after')) ?? DEFAULT_RETRY_MS;
+    noteRateLimited(TOKEN_OP, scope, delay);
+    throw new OzonError(`Performance API 授权接口限流（HTTP 429）：Retry-After=${Math.ceil(delay / 1000)} 秒，请告知用户稍后再查，不要重复重试。 `
+      + await errorText(response));
+  }
   if (!response.ok) {
     const fields = shop.legacy ? 'OZON_PERF_CLIENT_ID 和 OZON_PERF_CLIENT_SECRET' : `店铺「${shop.name}」的 perf_client_id 和 perf_client_secret`;
     const hint = response.status < 500
@@ -91,22 +167,27 @@ async function requestToken({ clientId, secret, shop }, agent) {
       : 'Ozon 授权服务暂时不可用，稍后再试。';
     throw new OzonError(`Performance API 授权失败（HTTP ${response.status}）：${hint} ${await errorText(response)}`);
   }
-  let data;
-  try {
-    data = parseJson((await readCapped(response)).toString('utf8'));
-  } catch {
-    throw new OzonError('Performance API 授权服务返回了无法解析的内容。');
-  }
+  const data = await readResponse(response, false, (raw) => {
+    try {
+      return parseJson(raw.toString('utf8'));
+    } catch {
+      throw new OzonError('Performance API 授权服务返回了无法解析的内容。');
+    }
+  });
   if (typeof data?.access_token !== 'string' || !data.access_token) throw new OzonError('Performance API 授权响应缺少 access_token。');
   const ttl = Number(data.expires_in) > 0 ? Number(data.expires_in) * 1000 : DEFAULT_TOKEN_TTL_MS;
+  // Registered before first use, so no output or log line can carry it unredacted.
+  rememberToken(data.access_token, Date.now() + ttl);
   return { clientId, value: data.access_token, expiresAt: Date.now() + Math.max(ttl - TOKEN_MARGIN_MS, ttl / 2) };
 }
 
-// `rejected` is the token that just got a 401: a newer cached token is reused, otherwise a new one is fetched.
-async function getToken(credentials, agent, rejected) {
+// `rejected` is the token that just got a 401: a newer cached token is reused, otherwise a new one is
+// fetched. The caller waits within its own budget (`signal`); the shared request is not cancelled.
+async function getToken(credentials, agent, rejected, signal) {
   const { clientId } = credentials;
   const cached = cachedTokens.get(clientId);
   if (cached && cached.value !== rejected && Date.now() < cached.expiresAt) return cached.value;
+  if (signal?.aborted) throw notSent();
   if (!pendingTokens.has(clientId)) {
     const promise = requestToken(credentials, agent)
       .then((token) => {
@@ -118,7 +199,7 @@ async function getToken(credentials, agent, rejected) {
       });
     pendingTokens.set(clientId, promise);
   }
-  return pendingTokens.get(clientId);
+  return untilAborted(pendingTokens.get(clientId), signal);
 }
 
 function buildUrl(op, params) {
@@ -143,9 +224,12 @@ function buildUrl(op, params) {
 
 const ZIP_NOTE = '这是多个活动打包的 ZIP 报告，本服务不解压。请每次只传一个活动重新生成，或改用对应的 /json 接口。';
 
-async function readBody(response) {
+function readBody(response, write) {
   const type = (response.headers.get('content-type') ?? '').toLowerCase();
-  const raw = await readCapped(response);
+  return readResponse(response, write, (raw) => decodeBody(type, raw));
+}
+
+function decodeBody(type, raw) {
   if (type.includes('json')) {
     if (!raw.length) return {};
     try {
@@ -169,7 +253,7 @@ function failureHint(status, retryAfter) {
   return '检查参数是否符合官方说明（ozon_ads_api_catalog 传 endpoint 可查看）。';
 }
 
-async function execute(op, url, payload, credentials, agent) {
+async function execute(op, url, payload, credentials, agent, signal) {
   const start = performance.now();
   const headers = { Accept: 'application/json, text/csv', 'User-Agent': USER_AGENT };
   let body;
@@ -178,44 +262,80 @@ async function execute(op, url, payload, credentials, agent) {
     if (Buffer.byteLength(body) > MAX_BODY) throw new OzonError('请求体过大，请缩小查询范围。');
     headers['Content-Type'] = 'application/json';
   }
-  let token = await getToken(credentials, agent);
+  const scope = accountScope(credentials.clientId);
+  // A report submission is classified read-only, but repeating it could start a second report:
+  // like a write, it is never retried automatically.
+  const retryable = op.read_only && !isReportSubmit(op);
+  const bodyTimedOut = `读取 Ozon 响应超过本次调用的时间预算，已取消。${op.read_only ? '' : WRITE_UNKNOWN}`;
+  if (signal?.aborted) throw notSent();
+  // Fails before fetching a token when a long cooldown is on; the send itself is counted in send().
+  checkAdmission(op, Date.now(), scope);
+  let token = await getToken(credentials, agent, undefined, signal);
+  // The token stays listed for redaction while this request uses it, even if it is replaced meanwhile.
+  let release = holdToken(token);
   let refreshed = false;
   let retried = false;
-  // At most one token refresh (a 401 means nothing was executed) and one retry for reads.
-  for (;;) {
-    const response = await send(url, { method: op.method, headers: { ...headers, Authorization: `Bearer ${token}` }, body }, agent,
-      { write: !op.read_only });
-    await rejectRedirect(response, op.path);
-    if (response.status === 401 && !refreshed) {
-      await response.body?.cancel().catch(() => {});
-      refreshed = true;
-      token = await getToken(credentials, agent, token);
-      continue;
-    }
-    if (!response.ok) {
-      const retryAfter = response.headers.get('retry-after') ?? '2';
-      const delay = Number.isFinite(Number(retryAfter)) ? Math.max(0, Number(retryAfter)) : 2;
-      if (op.read_only && !retried && RETRY_STATUSES.has(response.status) && delay <= 5) {
-        await response.body?.cancel().catch(() => {});
-        retried = true;
-        await sleep(delay * 1000);
+  try {
+    // At most one token refresh (a 401 means nothing was executed) and one retry for reads, within
+    // the account's retry budget. Every send waits out the account's shared 429 cooldown.
+    for (;;) {
+      let response;
+      try {
+        response = await send(url, { method: op.method, headers: { ...headers, Authorization: `Bearer ${token}` }, body }, agent,
+          { write: !op.read_only, scope, op, signal });
+      } catch (error) {
+        throw error.fetchFailed ? outcomeUnknown(error) : error;
+      }
+      rejectRedirect(response, op.path);
+      if (response.status === 401 && !refreshed) {
+        discardBody(response);
+        refreshed = true;
+        release();
+        token = await getToken(credentials, agent, token, signal);
+        release = holdToken(token);
         continue;
       }
-      throw new OzonError(`HTTP ${response.status} ${op.method} ${op.path}：${failureHint(response.status, retryAfter)} ${await errorText(response, token)}`);
+      if (!response.ok) {
+        const delay = parseRetryAfter(response.headers.get('retry-after')) ?? DEFAULT_RETRY_MS;
+        if (response.status === 429) noteRateLimited(op, scope, delay);
+        if (retryable && !retried && RETRY_STATUSES.has(response.status) && delay <= MAX_RETRY_WAIT_MS && admitRetry(op, scope)) {
+          discardBody(response);
+          retried = true;
+          try {
+            await sleep(withJitter(delay), signal);
+          } catch (error) {
+            throw signal?.aborted ? notSent() : error;
+          }
+          continue;
+        }
+        const failure = new OzonError(`HTTP ${response.status} ${op.method} ${op.path}：${failureHint(response.status, Math.ceil(delay / 1000))} `
+          + await untilAborted(errorText(response, !op.read_only), signal, bodyTimedOut).catch((error) => error.message));
+        throw response.status >= 500 ? outcomeUnknown(failure) : failure;
+      }
+      // Reading the body is part of the request: the budget covers it too.
+      let data;
+      try {
+        data = await untilAborted(readBody(response, !op.read_only), signal, bodyTimedOut);
+      } catch (error) {
+        throw outcomeUnknown(error);
+      }
+      return {
+        endpoint: op.path,
+        method: op.method,
+        http_status: response.status,
+        queried_at_utc: new Date().toISOString(),
+        elapsed_ms: Math.round(performance.now() - start),
+        data: redact(data),
+      };
     }
-    const data = await readBody(response);
-    return {
-      endpoint: op.path,
-      method: op.method,
-      http_status: response.status,
-      queried_at_utc: new Date().toISOString(),
-      elapsed_ms: Math.round(performance.now() - start),
-      data: scrubTokens(redact(data), token),
-    };
+  } finally {
+    release();
   }
 }
 
-export async function adsRequest(endpoint, { method = 'GET', params = {}, body } = {}) {
+// Checks everything that needs no network (mode, registry, parameters, credentials, proxy) and
+// returns the request ready to send. `signal` cancels it, waits included.
+export function prepareAdsRequest(endpoint, { method = 'GET', params = {}, body, signal } = {}) {
   const op = findAdsOperation(endpoint, method);
   if (!op) {
     throw new OzonError('广告接口路径或 HTTP 方法未在 Performance API 官方规范中登记，未发送请求；先用 ozon_ads_api_catalog 搜索。');
@@ -226,5 +346,10 @@ export async function adsRequest(endpoint, { method = 'GET', params = {}, body }
   const payload = validateAdsRequest(op, query, body);
   const url = buildUrl(op, query);
   const credentials = adsCredentials();
-  return execute(op, url, payload, credentials, getDispatcher());
+  const agent = getDispatcher();
+  return (sendSignal = signal) => execute(op, url, payload, credentials, agent, sendSignal);
+}
+
+export async function adsRequest(endpoint, options = {}) {
+  return prepareAdsRequest(endpoint, options)();
 }

package/src/ads/reports.js

@@ -0,0 +1,118 @@
+// One statistics report at a time per Performance account (Ozon's limit), with no background work.
+// Each account remembers the last report this process submitted: its UUID, status endpoint and
+// submission time. Before the next submission (an ozon_ads_stats batch or an ozon_ads_api_call
+// report, vendor reports included) the submitting call itself polls that report's status, within
+// its own time budget, until Ozon reports a final state or the report is MAX_AGE old. A per-account
+// queue makes "check previous → submit → record" one step, so two calls in this process cannot
+// both submit; it is released in `finally`, whatever happens.
+import { OzonError } from '../errors.js';
+import { sleep } from '../http.js';
+import { adsAccount, adsRequest, timeLimit, untilAborted } from './http.js';
+
+// Polling every 3 s; ozon_ads_stats as a whole and each report submission get 90 s; a report
+// submitted 120 s ago no longer holds the next one back.
+const DEFAULT_REPORT_TIMING = Object.freeze({ pollMs: 3000, waitMs: 90_000, maxAgeMs: 120_000 });
+export let reportTiming = DEFAULT_REPORT_TIMING;
+export function setReportTimingForTests(timing) {
+  reportTiming = { ...DEFAULT_REPORT_TIMING, ...timing };
+}
+
+// Final states. Vendor (external traffic) reports can also end as TIMEOUT or CANCEL.
+const FINISHED = new Set(['OK', 'ERROR', 'TIMEOUT', 'CANCEL']);
+export const isFinished = (state) => FINISHED.has(state);
+
+// Performance client id -> { uuid, status: { path, params }, submittedAt, finished }. A submission
+// that went out without a definite answer is kept as { uuid: null, unknown: true, submittedAt }: Ozon
+// may be building that report, so it holds the next one back until it is MAX_AGE old.
+const lastReports = new Map();
+const queues = new Map(); // Performance client id -> promise settled when the slot is free
+
+// Per-account state between tests; nothing runs in the background, so nothing needs stopping.
+export function resetReportSlots() {
+  lastReports.clear();
+  queues.clear();
+}
+
+// Whoever reads a report's status reports a final state here, so the next submission need not ask again.
+export function observeReportStatus(uuid, state) {
+  if (!isFinished(state)) return;
+  const last = lastReports.get(adsAccount());
+  if (last && last.uuid === String(uuid)) last.finished = true;
+}
+
+const describeLast = (last) => (last.unknown ? '上一份报表（已提交但结果未知）' : `上一份报表（UUID=${last.uuid}）`);
+const seconds = (ms) => Math.max(1, Math.ceil(ms / 1000));
+
+// The previous report may still be building: neither final nor MAX_AGE old. Only the call's own
+// budget running out stops the wait with an error; the age running out lets the submission go ahead.
+const budgetUsedUp = (last, ageLeft) => new OzonError(`本次调用的时间预算已用完：同一广告账号${describeLast(last)}还在生成或状态未知，`
+  + `还要约 ${seconds(ageLeft)} 秒才满 ${seconds(reportTiming.maxAgeMs)} 秒的等待上限，未提交新报表；请稍后再试。`);
+
+// Waits until the account's previous report is final or MAX_AGE old. Every status poll and every
+// pause is bounded by both the call's budget and the report's remaining age: when the age runs out
+// first, waiting stops and the submission goes ahead; when the budget runs out first, the caller
+// fails without submitting. A failed poll is not a final state. A placeholder (result unknown) has
+// no status to ask for: it is waited out, or refused at once when the budget cannot cover it.
+async function previousFinished(clientId, budget) {
+  const last = lastReports.get(clientId);
+  while (last && !last.finished) {
+    const ageLeft = last.submittedAt + reportTiming.maxAgeMs - Date.now();
+    if (ageLeft <= 0) return;
+    if (budget.signal?.aborted) throw budgetUsedUp(last, ageLeft);
+    if (last.unknown && budget.deadline !== undefined && budget.deadline - Date.now() < ageLeft) throw budgetUsedUp(last, ageLeft);
+    const age = timeLimit(ageLeft);
+    const signal = budget.signal ? AbortSignal.any([budget.signal, age.signal]) : age.signal;
+    try {
+      if (!last.unknown) {
+        const status = (await adsRequest(last.status.path, { params: { ...last.status.params, UUID: last.uuid }, signal })).data;
+        if (isFinished(status?.state)) {
+          last.finished = true;
+          return;
+        }
+      }
+      await sleep(last.unknown ? ageLeft : Math.min(reportTiming.pollMs, ageLeft), signal);
+    } catch {
+      // A failed or cut-off poll, or a pause ended early: the loop decides what happened.
+    } finally {
+      age.done();
+    }
+  }
+}
+
+// Runs `submit(signal)` as the account's next report submission and records the report it returns
+// (adsRequest result or its data, with a UUID) with `status`, where its state is read. A submission
+// that went out without a definite answer (error.outcomeUnknown, or no UUID) leaves a placeholder; one
+// that was never sent, or was refused outright, leaves nothing. Everything, the wait for the queue
+// included, stays within `budget` ({ signal, deadline }).
+export async function submitReport(status, submit, budget) {
+  const { signal } = budget;
+  const clientId = adsAccount();
+  const previous = queues.get(clientId) ?? Promise.resolve();
+  let release;
+  const mine = new Promise((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => mine);
+  queues.set(clientId, tail);
+  tail.then(() => {
+    if (queues.get(clientId) === tail) queues.delete(clientId);
+  });
+  try {
+    await untilAborted(previous, signal, '同一广告账号有其他报表正在提交，本次调用的时间预算内没轮到，未提交新报表；请稍后再试。');
+    await previousFinished(clientId, budget);
+    let result;
+    try {
+      result = await submit(signal);
+    } catch (error) {
+      if (error?.outcomeUnknown) lastReports.set(clientId, { uuid: null, unknown: true, submittedAt: Date.now(), finished: false });
+      throw error;
+    }
+    const uuid = (result?.data ?? result)?.UUID;
+    lastReports.set(clientId, uuid
+      ? { uuid: String(uuid), status, submittedAt: Date.now(), finished: false }
+      : { uuid: null, unknown: true, submittedAt: Date.now(), finished: false });
+    return result;
+  } finally {
+    release();
+  }
+}

package/src/ads/spec.js

@@ -28,6 +28,25 @@ export const READ_ONLY_IDS = new Set([
   'VendorStatisticsSubmitRequest', 'VendorStatisticsListReports', 'VendorStatisticsCheck', 'GetVendorTag',
 ]);
 
+// Asynchronous report submissions (each answers with a UUID to poll). Ozon builds one report at a
+// time per account, so these go through the account's report slot (see src/ads/reports.js), and
+// the status of each is read from its own endpoint: vendor (external traffic) reports have theirs.
+const REPORT_SUBMIT_IDS = new Set([
+  'SubmitRequest', 'VideoCampaignsSubmitRequest', 'AttributionSubmitRequest', 'SearchPromoOrdersReportSubmitRequest',
+  'SearchPromoProductsReportSubmitRequest', 'GenerateAllSkuPromoOrdersReport', 'GenerateAllSkuPromoProductsReport',
+  'ExternalStatistics_StatisticsPhrasesSubmitRequest2', 'VendorStatisticsSubmitRequest',
+]);
+const baseId = (op) => op.operation_id.replace(/_json$/, '');
+export const isReportSubmit = (op) => REPORT_SUBMIT_IDS.has(baseId(op));
+export const REPORT_STATUS_PATH = '/api/client/statistics/{UUID}';
+export const VENDOR_REPORT_STATUS_PATH = '/api/client/vendors/statistics/{UUID}';
+// Where a submission's report status is read: the endpoint and its fixed query parameters (the
+// vendor endpoint requires vendor=true, per its official description).
+export const REPORT_STATUS = Object.freeze({ path: REPORT_STATUS_PATH, params: {} });
+const VENDOR_REPORT_STATUS = Object.freeze({ path: VENDOR_REPORT_STATUS_PATH, params: { vendor: true } });
+export const reportStatus = (op) => (baseId(op) === 'VendorStatisticsSubmitRequest' ? VENDOR_REPORT_STATUS : REPORT_STATUS);
+export const isReportStatus = (op) => op.method === 'GET' && [REPORT_STATUS_PATH, VENDOR_REPORT_STATUS_PATH].includes(op.path);
+
 // Writes include GET endpoints that switch promotion on/off or set bids.
 export const WRITE_IDS = new Set([
   'CreateProductCampaignCPCV2', 'ActivateCampaign', 'DeactivateCampaign', 'PatchProductCampaign', 'AddProducts', 'UpdateProducts',