gangtise-openapi-cli 0.11.1 → 0.12.0

package/dist/src/core/client.js

@@ -1,21 +1,35 @@
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
 import { request } from "undici";
 import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
 import { ApiError, ValidationError } from "./errors.js";
 import { ENDPOINTS } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
+import { getDispatcher, isVerbose, logTiming, markRetryable, runWithConcurrency, withRetry } from "./transport.js";
+const PAGINATION_CONCURRENCY = Number(process.env.GANGTISE_PAGE_CONCURRENCY ?? 5) || 5;
+const AUTH_RETRY_CODES = new Set(["8000014", "8000015"]);
 export class GangtiseClient {
     config;
     refreshPromise = null;
+    memoCache = null;
     constructor(config) {
         this.config = config;
     }
-    async getAuthorizationHeader() {
-        if (this.config.token) {
+    async getAuthorizationHeader(forceRefresh = false) {
+        if (this.config.token && !forceRefresh) {
             return normalizeToken(this.config.token);
         }
-        const cache = await readTokenCache(this.config.tokenCachePath);
-        if (isTokenCacheValid(cache)) {
-            return normalizeToken(cache.accessToken);
+        if (!forceRefresh) {
+            if (isTokenCacheValid(this.memoCache)) {
+                return normalizeToken(this.memoCache.accessToken);
+            }
+            const cache = await readTokenCache(this.config.tokenCachePath);
+            if (isTokenCacheValid(cache)) {
+                this.memoCache = cache;
+                return normalizeToken(cache.accessToken);
+            }
         }
         if (!this.refreshPromise) {
             this.refreshPromise = this.doTokenRefresh().finally(() => { this.refreshPromise = null; });
@@ -30,11 +44,9 @@ export class GangtiseClient {
         }, false);
         const accessToken = normalizeToken(envelope.accessToken);
         const expiresAt = Math.floor(Date.now() / 1000) + envelope.expiresIn;
-        await writeTokenCache(this.config.tokenCachePath, {
-            ...envelope,
-            accessToken,
-            expiresAt,
-        });
+        const cache = { ...envelope, accessToken, expiresAt };
+        this.memoCache = cache;
+        await writeTokenCache(this.config.tokenCachePath, cache);
         return accessToken;
     }
     isEnvelope(parsed) {
@@ -100,55 +112,73 @@ export class GangtiseClient {
         const startFrom = typeof initialBody.from === 'number' && Number.isFinite(initialBody.from) ? initialBody.from : 0;
         const requestedSize = typeof initialBody.size === 'number' && Number.isFinite(initialBody.size) ? initialBody.size : undefined;
         const maxPageSize = endpoint.pagination?.maxPageSize ?? requestedSize ?? 20;
-        const collected = [];
-        let firstPage;
-        let total;
-        let nextFrom = startFrom;
+        // First page: serial — we need total before deciding how many more requests to fan out.
+        const firstPageSize = requestedSize === undefined ? maxPageSize : Math.min(maxPageSize, requestedSize);
+        const firstPage = await this.requestJson(endpoint, {
+            ...initialBody,
+            from: startFrom,
+            size: firstPageSize,
+        });
+        if (!this.isPaginatedListResponse(firstPage))
+            return firstPage;
+        const total = firstPage.total;
+        const collected = [...firstPage.list];
+        // Last page reached on first request
+        if (firstPage.list.length < firstPageSize) {
+            return {
+                ...firstPage,
+                total,
+                list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
+            };
+        }
+        const available = Math.max(total - startFrom, 0);
+        const target = requestedSize === undefined ? available : Math.min(requestedSize, available);
+        if (collected.length >= target) {
+            return {
+                ...firstPage,
+                total,
+                list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
+            };
+        }
+        const pageRequests = [];
+        let nextFrom = startFrom + firstPage.list.length;
+        const endFrom = startFrom + target;
+        while (nextFrom < endFrom) {
+            const remaining = endFrom - nextFrom;
+            const size = Math.min(maxPageSize, remaining);
+            pageRequests.push({ from: nextFrom, size });
+            nextFrom += size;
+        }
         const MAX_PAGES = 1000;
-        for (let pageCount = 0; pageCount < MAX_PAGES; pageCount++) {
-            const remaining = requestedSize === undefined
-                ? maxPageSize
-                : Math.min(maxPageSize, requestedSize - collected.length);
-            if (requestedSize !== undefined && remaining <= 0) {
-                break;
-            }
+        if (pageRequests.length + 1 > MAX_PAGES) {
+            pageRequests.length = MAX_PAGES - 1;
+        }
+        let unexpectedShape = false;
+        let totalDrift = false;
+        const pages = await runWithConcurrency(pageRequests, PAGINATION_CONCURRENCY, async (req) => {
             const page = await this.requestJson(endpoint, {
                 ...initialBody,
-                from: nextFrom,
-                size: remaining,
+                from: req.from,
+                size: req.size,
             });
             if (!this.isPaginatedListResponse(page)) {
-                if (!firstPage) {
-                    return page;
-                }
-                return {
-                    ...firstPage,
-                    total,
-                    list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
-                };
-            }
-            if (!firstPage) {
-                firstPage = page;
-                total = page.total;
-            }
-            if (page.list.length === 0) {
-                break;
-            }
-            collected.push(...page.list);
-            nextFrom += page.list.length;
-            const available = total === undefined ? undefined : Math.max(total - startFrom, 0);
-            if (requestedSize !== undefined && collected.length >= requestedSize) {
-                break;
-            }
-            if (available !== undefined && collected.length >= available) {
-                break;
-            }
-            if (page.list.length < remaining) {
-                break;
+                unexpectedShape = true;
+                return [];
             }
+            if (page.total !== total)
+                totalDrift = true;
+            return page.list;
+        });
+        for (const list of pages) {
+            if (list.length === 0)
+                continue;
+            collected.push(...list);
+        }
+        if (unexpectedShape && isVerbose()) {
+            process.stderr.write(`[gangtise] warning: a page response had unexpected shape; results may be incomplete\n`);
         }
-        if (!firstPage) {
-            return { total: 0, list: [] };
+        if (totalDrift && isVerbose()) {
+            process.stderr.write(`[gangtise] warning: 'total' changed across pages (data shifted during fetch)\n`);
         }
         return {
             ...firstPage,
@@ -168,100 +198,153 @@ export class GangtiseClient {
         if (endpoint.path.startsWith('/guide/')) {
             return this.readLocalLookup(endpoint);
         }
-        const headers = {
-            'content-type': 'application/json',
-        };
-        if (useAuth) {
-            headers.Authorization = await this.getAuthorizationHeader();
-        }
-        const response = await request(new URL(endpoint.path, this.config.baseUrl), {
-            method: endpoint.method,
-            headers,
-            body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
-            headersTimeout: this.config.timeoutMs,
-            bodyTimeout: this.config.timeoutMs,
-        });
-        const text = await response.body.text();
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            const message = response.statusCode >= 400
-                ? `API request failed (HTTP ${response.statusCode})`
-                : 'Failed to parse API response';
-            throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500));
-        }
-        if (response.statusCode >= 400) {
-            this.throwHttpError(parsed, response.statusCode);
-        }
-        return this.unwrapEnvelope(parsed, response.statusCode);
-    }
-    async download(endpoint, query) {
-        const authorization = await this.getAuthorizationHeader();
+        const dispatcher = getDispatcher();
         const url = new URL(endpoint.path, this.config.baseUrl);
-        Object.entries(query).forEach(([key, value]) => {
-            url.searchParams.set(key, String(value));
-        });
-        const response = await request(url, {
-            method: endpoint.method,
-            headers: {
-                Authorization: authorization,
-            },
-            headersTimeout: this.config.timeoutMs,
-            bodyTimeout: this.config.timeoutMs,
-        });
-        const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
-        if (contentType?.includes('application/json')) {
+        let authRetried = false;
+        return withRetry(async () => {
+            const headers = {
+                'content-type': 'application/json',
+            };
+            if (useAuth) {
+                headers.Authorization = await this.getAuthorizationHeader();
+            }
+            const startedAt = Date.now();
+            const response = await request(url, {
+                method: endpoint.method,
+                headers,
+                body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
+                headersTimeout: this.config.timeoutMs,
+                bodyTimeout: this.config.timeoutMs,
+                dispatcher,
+            });
             const text = await response.body.text();
+            logTiming(`${endpoint.method} ${endpoint.path}`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
             let parsed;
             try {
                 parsed = JSON.parse(text);
             }
             catch {
-                if (response.statusCode >= 400) {
-                    throw new ApiError('Download failed', undefined, response.statusCode, text);
-                }
-                return { text, contentType };
+                const message = response.statusCode >= 400
+                    ? `API request failed (HTTP ${response.statusCode})`
+                    : 'Failed to parse API response';
+                throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500));
             }
             if (response.statusCode >= 400) {
                 this.throwHttpError(parsed, response.statusCode);
             }
-            const data = this.unwrapEnvelope(parsed, response.statusCode);
-            if (data && typeof data === 'object' && 'url' in data && typeof data.url === 'string') {
-                return { url: String(data.url), contentType };
+            try {
+                return this.unwrapEnvelope(parsed, response.statusCode);
+            }
+            catch (error) {
+                // Auto-recover from auth errors by forcing a token refresh once.
+                if (useAuth
+                    && !authRetried
+                    && error instanceof ApiError
+                    && error.code
+                    && AUTH_RETRY_CODES.has(error.code)
+                    && (this.config.accessKey && this.config.secretKey)) {
+                    authRetried = true;
+                    this.memoCache = null;
+                    await this.getAuthorizationHeader(true);
+                    throw markRetryable(new ApiError(error.message, error.code, error.statusCode, error.details));
+                }
+                throw error;
+            }
+        }, {
+            onRetry: (attempt, error, delay) => {
+                if (!isVerbose())
+                    return;
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
+            },
+        });
+    }
+    async download(endpoint, query, options) {
+        const dispatcher = getDispatcher();
+        const url = new URL(endpoint.path, this.config.baseUrl);
+        Object.entries(query).forEach(([key, value]) => {
+            url.searchParams.set(key, String(value));
+        });
+        return withRetry(async () => {
+            const authorization = await this.getAuthorizationHeader();
+            const startedAt = Date.now();
+            const response = await request(url, {
+                method: endpoint.method,
+                headers: { Authorization: authorization },
+                headersTimeout: this.config.timeoutMs,
+                bodyTimeout: this.config.timeoutMs,
+                dispatcher,
+            });
+            const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
+            if (contentType?.includes('application/json')) {
+                const text = await response.body.text();
+                logTiming(`GET ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    if (response.statusCode >= 400) {
+                        throw new ApiError('Download failed', undefined, response.statusCode, text);
+                    }
+                    return { text, contentType };
+                }
+                if (response.statusCode >= 400) {
+                    this.throwHttpError(parsed, response.statusCode);
+                }
+                const data = this.unwrapEnvelope(parsed, response.statusCode);
+                if (data && typeof data === 'object' && 'url' in data && typeof data.url === 'string') {
+                    return { url: String(data.url), contentType };
+                }
+                return { text: JSON.stringify(data, null, 2), contentType };
+            }
+            if (contentType?.includes('text/plain') || contentType?.includes('text/html')) {
+                const text = await response.body.text();
+                logTiming(`GET ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                if (response.statusCode >= 400) {
+                    throw new ApiError('Download failed', undefined, response.statusCode, text);
+                }
+                return { text, contentType };
             }
-            return { text: JSON.stringify(data, null, 2), contentType };
-        }
-        if (contentType?.includes('text/plain') || contentType?.includes('text/html')) {
-            const text = await response.body.text();
             if (response.statusCode >= 400) {
+                const text = await response.body.text();
                 throw new ApiError('Download failed', undefined, response.statusCode, text);
             }
-            return { text, contentType };
-        }
-        if (response.statusCode >= 400) {
-            const text = await response.body.text();
-            throw new ApiError('Download failed', undefined, response.statusCode, text);
-        }
-        const buffer = await response.body.arrayBuffer();
-        const contentDisposition = response.headers['content-disposition'];
-        const filenameMatch = Array.isArray(contentDisposition)
-            ? contentDisposition[0]?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i)
-            : contentDisposition?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i);
-        return {
-            data: new Uint8Array(buffer),
-            contentType,
-            filename: filenameMatch ? decodeURIComponent(filenameMatch[1] || filenameMatch[2]) : undefined,
-        };
+            const contentDisposition = response.headers['content-disposition'];
+            const filenameMatch = Array.isArray(contentDisposition)
+                ? contentDisposition[0]?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i)
+                : contentDisposition?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i);
+            const filename = filenameMatch ? decodeURIComponent(filenameMatch[1] || filenameMatch[2]) : undefined;
+            // Stream directly to disk when caller already knows the destination
+            if (options?.streamTo) {
+                await fs.mkdir(path.dirname(options.streamTo), { recursive: true });
+                await pipeline(response.body, createWriteStream(options.streamTo));
+                logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
+                return { contentType, filename, savedPath: options.streamTo };
+            }
+            const buffer = await response.body.arrayBuffer();
+            logTiming(`GET ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
+            return {
+                data: new Uint8Array(buffer),
+                contentType,
+                filename,
+            };
+        }, {
+            onRetry: (attempt, error, delay) => {
+                if (!isVerbose())
+                    return;
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[gangtise] download retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
+            },
+        });
     }
-    async call(endpointKey, body, query) {
+    async call(endpointKey, body, query, options) {
         const endpoint = ENDPOINTS[endpointKey];
         if (!endpoint) {
             throw new ApiError(`Unknown endpoint key: ${endpointKey}`);
         }
         if (endpoint.kind === 'download') {
-            return this.download(endpoint, query ?? {});
+            return this.download(endpoint, query ?? {}, options);
         }
         if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
             return this.requestPaginated(endpoint, body);

package/dist/src/core/download.js

@@ -71,6 +71,10 @@ export async function saveDownloadResult(result, fallbackName, output) {
         throw new DownloadError("Unexpected download response");
     }
     const file = result;
+    if (typeof file.savedPath === "string") {
+        process.stdout.write(`${file.savedPath}\n`);
+        return;
+    }
     if (file.data instanceof Uint8Array) {
         const outputPath = output ?? file.filename ?? (fallbackName + extFromContentType(file.contentType));
         await saveOutputIfNeeded(file.data, outputPath);

package/dist/src/core/endpoints.js

@@ -70,7 +70,7 @@ export const ENDPOINTS = {
         method: "POST",
         path: "/application/open-insight/chief-opinion/getList",
         kind: "json",
-        description: "List chief opinions",
+        description: "List domestic institution chief opinions",
         pagination: { enabled: true, maxPageSize: 50 },
     },
     "insight.summary.list": {
@@ -155,7 +155,7 @@ export const ENDPOINTS = {
         method: "POST",
         path: "/application/open-insight/announcement/getList",
         kind: "json",
-        description: "List announcements",
+        description: "List A-share announcements",
         pagination: { enabled: true, maxPageSize: 50 },
     },
     "insight.announcement.download": {
@@ -163,7 +163,53 @@ export const ENDPOINTS = {
         method: "GET",
         path: "/application/open-insight/announcement/download/file",
         kind: "download",
-        description: "Download announcement file",
+        description: "Download A-share announcement file",
+    },
+    "insight.announcement-hk.list": {
+        key: "insight.announcement-hk.list",
+        method: "POST",
+        path: "/application/open-insight/announcement-hk/getList",
+        kind: "json",
+        description: "List HK announcements",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.announcement-hk.download": {
+        key: "insight.announcement-hk.download",
+        method: "GET",
+        path: "/application/open-insight/announcement-hk/download/file",
+        kind: "download",
+        description: "Download HK announcement file",
+    },
+    "insight.foreign-opinion.list": {
+        key: "insight.foreign-opinion.list",
+        method: "POST",
+        path: "/application/open-insight/foreign-opinion/getList",
+        kind: "json",
+        description: "List foreign institution opinions",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.independent-opinion.list": {
+        key: "insight.independent-opinion.list",
+        method: "POST",
+        path: "/application/open-insight/independent-opinion/getList",
+        kind: "json",
+        description: "List foreign independent analyst opinions",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.independent-opinion.download": {
+        key: "insight.independent-opinion.download",
+        method: "GET",
+        path: "/application/open-insight/independent-opinion/download/file",
+        kind: "download",
+        description: "Download foreign independent opinion file",
+    },
+    // ─── reference ───
+    "reference.securities-search": {
+        key: "reference.securities-search",
+        method: "POST",
+        path: "/application/open-reference/securities/search",
+        kind: "json",
+        description: "Search GTS codes (securities)",
     },
     // ─── quote ───
     "quote.day-kline": {

package/dist/src/core/output.js

@@ -100,6 +100,70 @@ export function renderOutput(value, format) {
             return renderTable(rows);
     }
 }
+/** Stream large jsonl/csv output row-by-row to avoid building a full string in memory. */
+export async function streamOutputToFile(value, format, outputPath) {
+    if (format !== "jsonl" && format !== "csv")
+        return false;
+    const list = pickListForStreaming(value);
+    if (!list)
+        return false;
+    // Below this row count the join() approach is cheaper than per-row writes.
+    if (list.length < 1000)
+        return false;
+    const { dirname } = await import("node:path");
+    const { createWriteStream } = await import("node:fs");
+    await fs.mkdir(dirname(outputPath), { recursive: true });
+    const stream = createWriteStream(outputPath, { encoding: "utf8" });
+    try {
+        if (format === "jsonl") {
+            for (const item of list) {
+                await writeLine(stream, JSON.stringify(item));
+            }
+        }
+        else {
+            const objectRows = list.filter((row) => Boolean(row && typeof row === "object" && !Array.isArray(row)));
+            const columns = Array.from(new Set(objectRows.flatMap((row) => Object.keys(row))));
+            await writeLine(stream, columns.join(","));
+            for (const row of objectRows) {
+                const cells = columns.map((column) => csvEscape(formatScalar(row[column])));
+                await writeLine(stream, cells.join(","));
+            }
+        }
+    }
+    finally {
+        await new Promise((resolve, reject) => {
+            stream.end((err) => err ? reject(err) : resolve());
+        });
+    }
+    return true;
+}
+function pickListForStreaming(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === "object") {
+        const list = value.list;
+        if (Array.isArray(list))
+            return list;
+    }
+    return null;
+}
+function csvEscape(value) {
+    let out = value;
+    if (/^[=+\-@\t\r]/.test(out))
+        out = "'" + out;
+    if (/[",\n]/.test(out))
+        return `"${out.replaceAll("\"", "\"\"")}"`;
+    return out;
+}
+function writeLine(stream, line) {
+    return new Promise((resolve, reject) => {
+        const ok = stream.write(line + "\n", (err) => err ? reject(err) : undefined);
+        if (ok)
+            resolve();
+        else
+            stream.once("drain", () => resolve());
+    });
+}
 export async function saveOutputIfNeeded(content, outputPath) {
     if (!outputPath) {
         return;

package/dist/src/core/printer.js

@@ -1,5 +1,5 @@
 import { normalizeRows } from "./normalize.js";
-import { renderOutput, saveOutputIfNeeded } from "./output.js";
+import { renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
 export async function printData(data, format, output, cache) {
     const normalized = normalizeRows(data);
@@ -21,11 +21,15 @@ export async function printData(data, format, output, cache) {
             process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
         }
     }
-    const content = renderOutput(normalized, format);
     if (output) {
+        if (await streamOutputToFile(normalized, format, output)) {
+            process.stdout.write(`${output}\n`);
+            return;
+        }
+        const content = renderOutput(normalized, format);
         await saveOutputIfNeeded(content, output);
         process.stdout.write(`${output}\n`);
         return;
     }
-    process.stdout.write(`${content}\n`);
+    process.stdout.write(`${renderOutput(normalized, format)}\n`);
 }

package/dist/src/core/quoteSharding.js

@@ -0,0 +1,81 @@
+import { runWithConcurrency } from "./transport.js";
+const DAY_MS = 86_400_000;
+function parseDate(value) {
+    // Accept yyyy-MM-dd; reject anything else so we can fall back to a single request.
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return null;
+    const d = new Date(`${value}T00:00:00Z`);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d;
+}
+function formatDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+function isAllMarket(body) {
+    const list = body.securityList;
+    if (!Array.isArray(list) || list.length !== 1)
+        return false;
+    return list[0] === "all";
+}
+function buildShards(start, end, shardDays) {
+    const shards = [];
+    let cursor = start.getTime();
+    const endTime = end.getTime();
+    while (cursor <= endTime) {
+        const shardEnd = Math.min(cursor + (shardDays - 1) * DAY_MS, endTime);
+        shards.push({
+            startDate: formatDate(new Date(cursor)),
+            endDate: formatDate(new Date(shardEnd)),
+        });
+        cursor = shardEnd + DAY_MS;
+    }
+    return shards;
+}
+/**
+ * For full-market (`--security all`) K-line queries that span more than `shardDays`,
+ * split the date range and run shards in parallel. Each shard is sized so the
+ * combined row count stays under the 10K-row API limit. For small ranges or
+ * single-security queries this is a no-op.
+ */
+export async function callKlineWithSharding(client, endpointKey, body, config) {
+    if (!isAllMarket(body) || !body.startDate || !body.endDate) {
+        return client.call(endpointKey, body);
+    }
+    const start = parseDate(body.startDate);
+    const end = parseDate(body.endDate);
+    if (!start || !end || end < start) {
+        return client.call(endpointKey, body);
+    }
+    const totalDays = Math.floor((end.getTime() - start.getTime()) / DAY_MS) + 1;
+    if (totalDays <= config.shardDays) {
+        return client.call(endpointKey, body);
+    }
+    const shards = buildShards(start, end, config.shardDays);
+    if (process.env.GANGTISE_VERBOSE === "1" || process.env.GANGTISE_VERBOSE === "true") {
+        process.stderr.write(`[gangtise] sharding ${endpointKey} into ${shards.length} requests (${config.shardDays} day(s) each)\n`);
+    }
+    const results = await runWithConcurrency(shards, config.concurrency ?? 5, async (shard) => {
+        return client.call(endpointKey, { ...body, startDate: shard.startDate, endDate: shard.endDate });
+    });
+    let fieldList;
+    let header = null;
+    const merged = [];
+    for (const r of results) {
+        if (!(r && typeof r === "object"))
+            continue;
+        const rec = r;
+        if (!header)
+            header = rec;
+        if (!fieldList && Array.isArray(rec.fieldList))
+            fieldList = rec.fieldList;
+        if (Array.isArray(rec.list))
+            merged.push(...rec.list);
+    }
+    if (!header)
+        return { list: [] };
+    const out = { ...header, list: merged };
+    if (fieldList)
+        out.fieldList = fieldList;
+    return out;
+}