@oomol-lab/open-connector 1.6.2 → 1.6.3

package/src/providers/buzzsprout/executors.js

@@ -0,0 +1,21 @@
+import { defineApiKeyProviderExecutors, defineProviderProxy } from "../provider-runtime.js";
+import { buzzsproutActionHandlers, buzzsproutApiBaseUrl, validateBuzzsproutCredential } from "./runtime.js";
+const service = "buzzsprout";
+export const executors = defineApiKeyProviderExecutors(service, buzzsproutActionHandlers, {
+    skipDnsValidation: true,
+});
+export const proxy = defineProviderProxy({
+    service,
+    baseUrl: buzzsproutApiBaseUrl,
+    auth: { type: "api_key_authorization", prefix: "Token token=" },
+    skipDnsValidation: true,
+    customizeRequest({ headers }) {
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+    },
+});
+export const credentialValidators = {
+    async apiKey(input, { fetcher, signal }) {
+        return validateBuzzsproutCredential(input.apiKey, fetcher, signal);
+    },
+};

package/src/providers/buzzsprout/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { ApiKeyProviderContext, ProviderActionHandlers } from "../provider-runtime.ts";
+export declare const buzzsproutApiBaseUrl = "https://www.buzzsprout.com/api";
+type Handler = (input: Record<string, unknown>, context: ApiKeyProviderContext) => Promise<unknown>;
+export declare const buzzsproutActionHandlers: ProviderActionHandlers<"buzzsprout", Handler>;
+export declare function validateBuzzsproutCredential(apiKey: string, fetcher: typeof fetch, signal?: AbortSignal): Promise<{
+    profile: {
+        displayName: string;
+    };
+    grantedScopes: string[];
+    metadata: Record<string, unknown>;
+}>;
+export {};

package/src/providers/buzzsprout/runtime.js

@@ -0,0 +1,237 @@
+import { compactObject, objectArray, optionalInteger, optionalRecord, optionalString, rawStringOrNull, requiredBoolean, requiredNumber, requiredRecord, requiredString, } from "../../core/cast.js";
+import { readProviderTextBody } from "../provider-runtime.js";
+import { providerResponseError, providerUserAgent, ProviderRequestError } from "../provider-runtime.js";
+export const buzzsproutApiBaseUrl = "https://www.buzzsprout.com/api";
+export const buzzsproutActionHandlers = {
+    async list_podcasts(_input, context) {
+        return { podcasts: objects(await request("/podcasts", context), "Buzzsprout podcasts").map(normalizePodcast) };
+    },
+    async get_podcast(input, context) {
+        return { podcast: normalizePodcast(await request(`/podcasts/${id(input.podcastId, "podcastId")}`, context)) };
+    },
+    async update_podcast(input, context) {
+        return {
+            podcast: normalizePodcast(await request(`/podcasts/${id(input.podcastId, "podcastId")}`, context, "PATCH", podcastBody(input))),
+        };
+    },
+    async list_episodes(input, context) {
+        return {
+            episodes: objects(await request(`/${id(input.podcastId, "podcastId")}/episodes`, context), "Buzzsprout episodes").map(normalizeEpisode),
+        };
+    },
+    async get_episode(input, context) {
+        return {
+            episode: normalizeEpisode(await request(`/${id(input.podcastId, "podcastId")}/episodes/${id(input.episodeId, "episodeId")}`, context)),
+        };
+    },
+    async create_episode(input, context) {
+        return {
+            episode: normalizeEpisode(await request(`/${id(input.podcastId, "podcastId")}/episodes`, context, "POST", episodeBody(input))),
+        };
+    },
+    async update_episode(input, context) {
+        return {
+            episode: normalizeEpisode(await request(`/${id(input.podcastId, "podcastId")}/episodes/${id(input.episodeId, "episodeId")}`, context, "PATCH", episodeBody(input))),
+        };
+    },
+    async list_podcast_downloads(input, context) {
+        const payload = objects(await request(`/${id(input.podcastId, "podcastId")}/downloads`, context, "GET", undefined, {
+            date: optionalString(input.date),
+        }), "Buzzsprout podcast downloads");
+        return {
+            downloads: payload.map((value) => {
+                const record = requiredRecord(value, "Buzzsprout podcast download", providerResponseError);
+                return {
+                    episodeId: positive(record.episode_id, "Buzzsprout download episode_id"),
+                    total: nonNegative(record.total, "Buzzsprout download total"),
+                };
+            }),
+        };
+    },
+    async list_episode_downloads(input, context) {
+        const payload = requiredRecord(await request(`/${id(input.podcastId, "podcastId")}/${id(input.episodeId, "episodeId")}/downloads`, context, "GET", undefined, { date: optionalString(input.date), page: stringInteger(input.page), per_page: stringInteger(input.perPage) }), "Buzzsprout episode downloads", providerResponseError);
+        const episode = objects(payload.episodes, "Buzzsprout episode downloads episodes")[0];
+        if (!episode)
+            throw providerResponseError("Buzzsprout episode downloads response is empty");
+        const pagination = requiredRecord(payload.pagination, "Buzzsprout pagination", providerResponseError);
+        return {
+            episodeId: positive(episode.id, "Buzzsprout episode id"),
+            downloads: objects(episode.downloads, "Buzzsprout downloads").map(normalizeDownload),
+            page: positive(pagination.page, "Buzzsprout pagination page"),
+            perPage: positive(pagination.per_page, "Buzzsprout pagination per_page"),
+            hasMore: requiredBoolean(pagination.has_more, "Buzzsprout pagination has_more", providerResponseError),
+            nextPage: pagination.next_page == null ? null : positive(pagination.next_page, "Buzzsprout pagination next_page"),
+        };
+    },
+};
+export async function validateBuzzsproutCredential(apiKey, fetcher, signal) {
+    const context = { apiKey, fetcher, signal };
+    const podcasts = objects(await request("/podcasts", context), "Buzzsprout podcasts");
+    return {
+        profile: { displayName: optionalString(optionalRecord(podcasts[0])?.title) ?? "Buzzsprout API Token" },
+        grantedScopes: [],
+        metadata: { apiBaseUrl: buzzsproutApiBaseUrl, validationEndpoint: "/podcasts", podcastCount: podcasts.length },
+    };
+}
+function podcastBody(input) {
+    return compactObject({
+        title: input.title,
+        description: input.description,
+        keywords: input.keywords,
+        author: input.author,
+        explicit: input.explicit,
+        language: input.language,
+        timezone: input.timezone,
+        website_address: input.websiteAddress,
+        contact_email: input.contactEmail,
+        category: input.category,
+        category2: input.category2,
+        category3: input.category3,
+        artwork_url: input.artworkUrl,
+    });
+}
+function episodeBody(input) {
+    return compactObject({
+        title: input.title,
+        description: input.description,
+        artist: input.artist,
+        tags: input.tags,
+        published_at: input.publishedAt,
+        season_number: input.seasonNumber,
+        episode_number: input.episodeNumber,
+        episode_type: input.episodeType,
+        explicit: input.explicit,
+        private: input.private,
+        custom_url: input.customUrl,
+        artwork_url: input.artworkUrl,
+    });
+}
+async function request(path, context, method = "GET", body, query) {
+    const url = new URL(`${buzzsproutApiBaseUrl}${path}`);
+    for (const [key, value] of Object.entries(query ?? {}))
+        if (value !== undefined)
+            url.searchParams.set(key, value);
+    const response = await context.fetcher(url, {
+        method,
+        headers: {
+            accept: "application/json",
+            authorization: `Token token=${context.apiKey}`,
+            "content-type": "application/json; charset=utf-8",
+            "user-agent": providerUserAgent,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: context.signal,
+    });
+    const text = await readProviderTextBody(response, "Buzzsprout response");
+    let payload = null;
+    try {
+        payload = text ? JSON.parse(text) : null;
+    }
+    catch {
+        if (response.ok)
+            throw providerResponseError("Buzzsprout returned invalid JSON");
+        payload = text;
+    }
+    if (!response.ok)
+        throw new ProviderRequestError(response.status, errorMessage(payload) ?? `Buzzsprout request failed with status ${response.status}`, payload);
+    return payload;
+}
+function errorMessage(payload) {
+    if (typeof payload === "string")
+        return payload.trim() || undefined;
+    const record = optionalRecord(payload), nested = optionalRecord(record?.error);
+    return optionalString(nested?.message) ?? optionalString(record?.message) ?? optionalString(record?.error);
+}
+function normalizePodcast(value) {
+    const r = requiredRecord(value, "Buzzsprout podcast", providerResponseError);
+    return {
+        id: positive(r.id, "podcast id"),
+        title: requiredString(r.title, "podcast title", providerResponseError),
+        author: rawStringOrNull(r.author),
+        description: rawStringOrNull(r.description),
+        websiteAddress: rawStringOrNull(r.website_address),
+        websiteUrl: rawStringOrNull(r.website_url),
+        contactEmail: rawStringOrNull(r.contact_email),
+        keywords: rawStringOrNull(r.keywords),
+        explicit: requiredBoolean(r.explicit, "podcast explicit", providerResponseError),
+        mainCategory: rawStringOrNull(r.main_category),
+        subCategory: rawStringOrNull(r.sub_category),
+        mainCategory2: rawStringOrNull(r.main_category2),
+        subCategory2: rawStringOrNull(r.sub_category2),
+        mainCategory3: rawStringOrNull(r.main_category3),
+        subCategory3: rawStringOrNull(r.sub_category3),
+        language: rawStringOrNull(r.language),
+        timezone: rawStringOrNull(r.timezone),
+        artworkUrl: rawStringOrNull(r.artwork_url),
+        backgroundUrl: rawStringOrNull(r.background_url),
+        rssUrl: rawStringOrNull(r.rss_url),
+        raw: r,
+    };
+}
+function normalizeEpisode(value) {
+    const r = requiredRecord(value, "Buzzsprout episode", providerResponseError);
+    return {
+        id: positive(r.id, "episode id"),
+        title: requiredString(r.title, "episode title", providerResponseError),
+        audioUrl: rawStringOrNull(r.audio_url),
+        artworkUrl: rawStringOrNull(r.artwork_url),
+        description: rawStringOrNull(r.description),
+        artist: rawStringOrNull(r.artist),
+        tags: rawStringOrNull(r.tags),
+        publishedAt: rawStringOrNull(r.published_at),
+        duration: optionalIntegerAtLeast(r.duration, "episode duration", -1),
+        guid: rawStringOrNull(r.guid),
+        customUrl: rawStringOrNull(r.custom_url),
+        episodeNumber: optionalIntegerAtLeast(r.episode_number, "episode number", 0),
+        seasonNumber: optionalIntegerAtLeast(r.season_number, "season number", 0),
+        episodeType: rawStringOrNull(r.episode_type),
+        explicit: requiredBoolean(r.explicit, "episode explicit", providerResponseError),
+        private: requiredBoolean(r.private, "episode private", providerResponseError),
+        totalPlays: optionalIntegerAtLeast(r.total_plays, "episode total plays", 0),
+        raw: r,
+    };
+}
+function normalizeDownload(value) {
+    const r = requiredRecord(value, "Buzzsprout download", providerResponseError);
+    return {
+        app: requiredString(r.app, "download app", providerResponseError),
+        device: requiredString(r.device, "download device", providerResponseError),
+        deviceType: requiredString(r.device_type, "download device_type", providerResponseError),
+        countryCode: rawStringOrNull(r.country_code),
+        region: rawStringOrNull(r.region),
+        city: rawStringOrNull(r.city),
+        continent: rawStringOrNull(r.continent),
+        mediaType: requiredString(r.media_type, "download media_type", providerResponseError),
+    };
+}
+function objects(value, label) {
+    return objectArray(value, label, providerResponseError);
+}
+function id(value, label) {
+    return positive(value, label);
+}
+function positive(value, label) {
+    const number = requiredNumber(value, label, providerResponseError);
+    if (!Number.isInteger(number) || number <= 0)
+        throw providerResponseError(`${label} must be a positive integer`);
+    return number;
+}
+function nonNegative(value, label) {
+    const number = requiredNumber(value, label, providerResponseError);
+    if (!Number.isInteger(number) || number < 0)
+        throw providerResponseError(`${label} must be a non-negative integer`);
+    return number;
+}
+function stringInteger(value) {
+    const number = optionalInteger(value);
+    return number === undefined ? undefined : String(number);
+}
+function optionalIntegerAtLeast(value, label, minimum) {
+    if (value == null)
+        return null;
+    const number = requiredNumber(value, label, providerResponseError);
+    if (!Number.isInteger(number) || number < minimum) {
+        throw providerResponseError(`${label} must be an integer of at least ${minimum}`);
+    }
+    return number;
+}

package/src/providers/feishu/shared/drive-actions.d.ts

@@ -1,6 +1,7 @@
 import type { ActionDefinition } from "../../../core/types.ts";
 export declare const feishuDriveProviderScopes: {
     metadataRead: string;
+    folderList: string;
     search: string;
     folderCreate: string;
     copy: string;

package/src/providers/feishu/shared/drive-actions.js

@@ -2,6 +2,7 @@ import { s } from "../../../core/json-schema.js";
 import { defineProviderAction } from "../../../core/provider-definition.js";
 export const feishuDriveProviderScopes = {
     metadataRead: "drive:drive.metadata:readonly",
+    folderList: "space:document:retrieve",
     search: "search:docs:read",
     folderCreate: "space:folder:create",
     copy: "docs:document:copy",
@@ -12,7 +13,7 @@ export const feishuDriveProviderScopes = {
     commentCreate: "docs:document.comment:create",
     commentUpdate: "docs:document.comment:update",
     commentDelete: "docs:document.comment:delete",
-    permissionRead: "docs:permission.member:readonly",
+    permissionRead: "docs:permission.member:retrieve",
     permissionCreate: "docs:permission.member:create",
     permissionUpdate: "docs:permission.member:update",
     permissionDelete: "docs:permission.member:delete",
@@ -154,8 +155,11 @@ export function createFeishuDriveActions(service) {
             name: "list_drive_files",
             operationType: "read",
             description: "List files, folders, and online documents inside a Feishu Drive folder.",
-            requiredScopes: [feishuDriveProviderScopes.metadataRead],
-            providerPermissions: [feishuDriveProviderScopes.metadataRead],
+            // Measured against Feishu with a user_access_token on 2026-09-14:
+            // metadataRead is rejected with 99991679, which names folderList as the
+            // narrowest accepted permission for this endpoint.
+            requiredScopes: [feishuDriveProviderScopes.folderList],
+            providerPermissions: [feishuDriveProviderScopes.folderList],
             inputSchema: s.object("Choose a folder, sort order, and page.", {
                 folderToken: s.string("The folder token to list; omit it to list the caller's root folder.", {
                     minLength: 1,
@@ -381,7 +385,7 @@ export function createFeishuDriveActions(service) {
             inputSchema: permissionResourceSchema({
                 fields: s.string("A comma-separated projection of permission member fields."),
                 permType: s.stringEnum("The Wiki permission scope.", ["container", "single_page"]),
-            }),
+            }, ["fields", "permType"]),
             outputSchema: s.object("The permission members on a Drive resource.", {
                 members: s.array("The permission members.", permissionSchema),
             }, {
@@ -405,7 +409,7 @@ export function createFeishuDriveActions(service) {
                     "wiki_space_editor",
                 ]),
                 needNotification: s.boolean("Whether Feishu should notify the collaborator."),
-            }),
+            }, ["permType", "memberKind", "needNotification"]),
             outputSchema: s.object("The granted Drive permission.", {
                 member: {
                     ...permissionSchema,
@@ -426,7 +430,7 @@ export function createFeishuDriveActions(service) {
                 memberType: memberTypeSchema,
                 permission: permissionRoleSchema,
                 needNotification: s.boolean("Whether Feishu should notify the collaborator."),
-            }),
+            }, ["needNotification"]),
             outputSchema: s.object("The updated Drive permission.", {
                 member: {
                     ...permissionSchema,
@@ -446,7 +450,7 @@ export function createFeishuDriveActions(service) {
                 memberId: s.string("The collaborator identifier.", { minLength: 1 }),
                 memberType: memberTypeSchema,
                 permType: s.stringEnum("The Wiki permission scope.", ["container", "single_page"]),
-            }),
+            }, ["permType"]),
             outputSchema: deletionOutputSchema("Whether the Drive permission was removed."),
         }),
     ];
@@ -491,12 +495,12 @@ function commentIdentitySchema(extra) {
         optional: [],
     });
 }
-function permissionResourceSchema(extra) {
+function permissionResourceSchema(extra, optional) {
     return s.object("Identify a Feishu Drive permission resource and operation.", {
         token: resourceTokenSchema,
         resourceType: permissionResourceTypeSchema,
         ...extra,
     }, {
-        optional: [],
+        optional,
     });
 }

package/src/providers/feishu/shared/drive-runtime.js

@@ -295,9 +295,21 @@ async function listDrivePermissions(input, request) {
             perm_type: optionalString(input.permType),
         },
     });
-    return {
-        members: Array.isArray(data.members) ? data.members : [],
-    };
+    // Feishu answers `GET /drive/v1/permissions/:token/members` with the
+    // collaborators under `data.items`, not `data.members`. Reading the output
+    // name as if it were the wire key missed every time, and the `: []` below
+    // turned the miss into a successful empty list — so every ACL read reported
+    // that nobody has access, with `success: true`.
+    //
+    // Every other list endpoint in this file already names the wire key
+    // explicitly (`normalizePage(data, "files")`, `normalizePage(data,
+    // "items")`); this one assumed it matched the field it returns, and was the
+    // only place that did.
+    //
+    // `members` is still read after `items`, so a wire that ever answers under
+    // that name keeps working rather than breaking in the other direction.
+    const rows = Array.isArray(data.items) ? data.items : Array.isArray(data.members) ? data.members : [];
+    return { members: rows };
 }
 async function addDrivePermission(input, request) {
     const memberType = requireString(input.memberType, "memberType");

package/src/providers/feishu/shared/wiki-actions.js

@@ -101,8 +101,10 @@ export function createFeishuWikiActions(service) {
             name: "get_wiki_node",
             operationType: "read",
             description: "Resolve and get a Feishu Wiki node by token and object type.",
-            requiredScopes: ["wiki:node:retrieve"],
-            providerPermissions: ["wiki:node:retrieve"],
+            // Feishu refuses `wiki:node:retrieve` for this endpoint with 99991679
+            // and names `wiki:node:read` as the narrow accepted permission.
+            requiredScopes: ["wiki:node:read"],
+            providerPermissions: ["wiki:node:read"],
             inputSchema: s.object("Identify the Wiki node.", {
                 token: s.string("A Wiki node_token or document obj_token.", { minLength: 1 }),
                 objectType,

package/src/providers/hithink_finance/runtime.js

@@ -1,33 +1,12 @@
-import { compactObject } from "../../core/cast.js";
-import { runProviderRequest, ProviderRequestError, providerUserAgent } from "../provider-runtime.js";
+import { compactObject, optionalInteger, optionalNumber, optionalString, optionalStringArray, } from "../../core/cast.js";
+import { requiredInputNumber, requiredInputString, runProviderRequest, ProviderRequestError, providerUserAgent, } from "../provider-runtime.js";
 import { createMarketDumpHandlers } from "./market-dumps.js";
-function requiredString(value, fieldName) {
-    if (typeof value !== "string" || !value.trim()) {
-        throw hithinkError("invalid_input", `${fieldName} is required`, 400);
-    }
-    return value.trim();
-}
-function optionalString(value) {
-    return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-function optionalStringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
-}
 function requiredStringArray(value, fieldName) {
     const result = optionalStringArray(value);
     if (!result || result.length === 0) {
         throw hithinkError("invalid_input", `${fieldName} is required`, 400);
     }
-    return result.map((item, index) => requiredString(item, `${fieldName}[${index}]`));
-}
-function optionalNumber(value) {
-    return typeof value === "number" ? value : undefined;
-}
-function requiredNumber(value, fieldName) {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw hithinkError("invalid_input", `${fieldName} is required`, 400);
-    }
-    return value;
+    return result.map((item, index) => requiredInputString(item, `${fieldName}[${index}]`));
 }
 export const hithinkFinanceProxyMaxResponseBytes = 4 * 1024 * 1024;
 const hithinkFinanceActionMaxResponseBytes = 16 * 1024 * 1024;
@@ -75,7 +54,7 @@ export async function fetchHithinkFinanceProxy(input) {
         }
         throw error;
     }
-    const code = readInteger(payload.code);
+    const code = optionalInteger(payload.code);
     if (!response.ok || code !== 0) {
         throw buildProviderError(response.status, code, payload, "execute");
     }
@@ -130,7 +109,7 @@ async function readBoundedResponse(response, maximumBytes, tooLargeError, emptyM
 export const hithinkFinanceActionHandlers = {
     search_tickers(input, context) {
         return get("/api/meta/tickers/search", {
-            q: requiredString(input.query, "query"),
+            q: requiredInputString(input.query, "query"),
             exchange: optionalString(input.exchange),
             asset_type: optionalStringArray(input.assetTypes)?.join(","),
             limit: optionalNumber(input.limit),
@@ -153,17 +132,17 @@ export const hithinkFinanceActionHandlers = {
     },
     get_stock_history(input, context) {
         return get("/api/a-share/prices/historical", {
-            thscode: requiredString(input.thscode, "thscode"),
+            thscode: requiredInputString(input.thscode, "thscode"),
             interval: "1d",
-            start: requiredNumber(input.startTimeMs, "startTimeMs"),
-            end: requiredNumber(input.endTimeMs, "endTimeMs"),
+            start: requiredInputNumber(input.startTimeMs, "startTimeMs"),
+            end: requiredInputNumber(input.endTimeMs, "endTimeMs"),
             adjust: optionalString(input.adjust),
             offset: optionalNumber(input.offset),
         }, context);
     },
     get_adjustment_factors(input, context) {
         return get("/api/a-share/corporate-actions/adjustment-factors", {
-            thscode: requiredString(input.thscode, "thscode"),
+            thscode: requiredInputString(input.thscode, "thscode"),
             from: optionalString(input.from),
             to: optionalString(input.to),
         }, context);
@@ -179,8 +158,8 @@ export const hithinkFinanceActionHandlers = {
     },
     get_financial_indicators(input, context) {
         return get("/api/a-share/financials/indicators", {
-            thscode: requiredString(input.thscode, "thscode"),
-            report: requiredString(input.report, "report"),
+            thscode: requiredInputString(input.thscode, "thscode"),
+            report: requiredInputString(input.report, "report"),
         }, context);
     },
     get_valuation_snapshot(input, context) {
@@ -193,17 +172,17 @@ export const hithinkFinanceActionHandlers = {
         return get("/api/a-share-index/catalog/ths-index-list", { tag: optionalString(input.tag) }, context);
     },
     get_index_constituents(input, context) {
-        return get("/api/a-share-index/constituents/ths-stock-list", { thscode: requiredString(input.thscode, "thscode") }, context);
+        return get("/api/a-share-index/constituents/ths-stock-list", { thscode: requiredInputString(input.thscode, "thscode") }, context);
     },
     get_index_snapshot(input, context) {
         return get("/api/a-share-index/prices/snapshot", { thscodes: requiredStringArray(input.thscodes, "thscodes").join(",") }, context);
     },
     get_index_history(input, context) {
         return get("/api/a-share-index/prices/historical", {
-            thscode: requiredString(input.thscode, "thscode"),
+            thscode: requiredInputString(input.thscode, "thscode"),
             interval: "1d",
-            start: requiredNumber(input.startTimeMs, "startTimeMs"),
-            end: requiredNumber(input.endTimeMs, "endTimeMs"),
+            start: requiredInputNumber(input.startTimeMs, "startTimeMs"),
+            end: requiredInputNumber(input.endTimeMs, "endTimeMs"),
         }, context);
     },
     get_auction_snapshot(input, context) {
@@ -242,26 +221,26 @@ function createFundHandlers(get) {
             });
         },
         get_fund_market_snapshot(input, context) {
-            return get("/api/fund/market/snapshot", { thscode: requiredString(input.thscode, "thscode") }, context);
+            return get("/api/fund/market/snapshot", { thscode: requiredInputString(input.thscode, "thscode") }, context);
         },
         get_fund_market_history(input, context) {
             return get("/api/fund/market/historical", {
-                thscode: requiredString(input.thscode, "thscode"),
+                thscode: requiredInputString(input.thscode, "thscode"),
                 interval: "1d",
-                start: requiredNumber(input.startTimeMs, "startTimeMs"),
-                end: requiredNumber(input.endTimeMs, "endTimeMs"),
+                start: requiredInputNumber(input.startTimeMs, "startTimeMs"),
+                end: requiredInputNumber(input.endTimeMs, "endTimeMs"),
             }, context);
         },
         get_fund_company(input, context) {
-            return get("/api/fund/companies/detail", { company_id: requiredString(input.companyId, "companyId") }, context);
+            return get("/api/fund/companies/detail", { company_id: requiredInputString(input.companyId, "companyId") }, context);
         },
         get_fund_industry_allocation(input, context) {
             return getFund(get, "/api/fund/portfolio/industry-allocation", input, context);
         },
         get_fund_performance_indicators(input, context) {
             return getFund(get, "/api/fund/performance/indicators-historical", input, context, {
-                start: requiredNumber(input.startTimeMs, "startTimeMs"),
-                end: requiredNumber(input.endTimeMs, "endTimeMs"),
+                start: requiredInputNumber(input.startTimeMs, "startTimeMs"),
+                end: requiredInputNumber(input.endTimeMs, "endTimeMs"),
             });
         },
         get_fund_drawdowns(input, context) {
@@ -292,7 +271,7 @@ function createFundHandlers(get) {
         },
         get_fund_manager_performance(input, context) {
             return getManager(get, "/api/fund/managers/performance", input, context, {
-                range: requiredString(input.range, "range"),
+                range: requiredInputString(input.range, "range"),
             });
         },
         get_fund_manager_experience(input, context) {
@@ -308,7 +287,7 @@ function createFundHandlers(get) {
             });
         },
         list_fund_offerings(input, context) {
-            return get("/api/fund/offerings/list", { subscribe: requiredString(input.subscriptionStatus, "subscriptionStatus") }, context);
+            return get("/api/fund/offerings/list", { subscribe: requiredInputString(input.subscriptionStatus, "subscriptionStatus") }, context);
         },
         get_fund_stock_holdings_history(input, context) {
             return getFundHoldingsHistory(get, "/api/fund/portfolio/stock-history", input, context);
@@ -329,8 +308,8 @@ function createFundHandlers(get) {
 }
 function getFund(get, path, input, context, extra = {}) {
     return get(path, {
-        fund_type: requiredString(input.fundType, "fundType"),
-        thscode: requiredString(input.thscode, "thscode"),
+        fund_type: requiredInputString(input.fundType, "fundType"),
+        thscode: requiredInputString(input.thscode, "thscode"),
         ...extra,
     }, context);
 }
@@ -348,12 +327,12 @@ function normalizeNavTypes(value) {
     return undefined;
 }
 function getManager(get, path, input, context, extra = {}) {
-    return get(path, { manager_id: requiredString(input.managerId, "managerId"), ...extra }, context);
+    return get(path, { manager_id: requiredInputString(input.managerId, "managerId"), ...extra }, context);
 }
 function getFundHoldingsHistory(get, path, input, context) {
     return getFund(get, path, input, context, {
-        report_type: requiredString(input.reportType, "reportType"),
-        end_date: requiredString(input.endDate, "endDate"),
+        report_type: requiredInputString(input.reportType, "reportType"),
+        end_date: requiredInputString(input.endDate, "endDate"),
     });
 }
 function getFundReportDates(get, path, input, context) {
@@ -382,13 +361,13 @@ function createSpecialDataHandlers(get) {
             return get("/api/a-share/special-data/hot-stock-list", { period: optionalString(input.period) }, context);
         },
         get_hot_stock_history(input, context) {
-            return get("/api/a-share/special-data/hot-stock-list-history", { date: requiredString(input.date, "date") }, context);
+            return get("/api/a-share/special-data/hot-stock-list-history", { date: requiredInputString(input.date, "date") }, context);
         },
         get_hot_stock_rank_trend(input, context) {
             return get("/api/a-share/special-data/hot-stock-rank-trend", {
-                thscode: requiredString(input.thscode, "thscode"),
-                start_date: requiredString(input.startDate, "startDate"),
-                end_date: requiredString(input.endDate, "endDate"),
+                thscode: requiredInputString(input.thscode, "thscode"),
+                start_date: requiredInputString(input.startDate, "startDate"),
+                end_date: requiredInputString(input.endDate, "endDate"),
             }, context);
         },
         get_dragon_tiger_list(input, context) {
@@ -413,7 +392,7 @@ function getPool(get, path, input, context) {
 }
 function getFinancialStatements(path, input, context) {
     return get(path, {
-        thscode: requiredString(input.thscode, "thscode"),
+        thscode: requiredInputString(input.thscode, "thscode"),
         period: optionalString(input.period),
         limit: optionalNumber(input.limit),
         start: optionalNumber(input.startTimeMs),
@@ -455,7 +434,7 @@ async function hithinkFinanceGet(path, query, apiKey, fetcher, phase, signal) {
         }
         throw error;
     }
-    const code = readInteger(payload.code);
+    const code = optionalInteger(payload.code);
     if (!response.ok || code !== 0) {
         throw buildProviderError(response.status, code, payload, phase);
     }
@@ -500,7 +479,10 @@ function buildProviderError(status, code, payload, phase) {
         return hithinkError(phase === "validate" ? "invalid_input" : "scope_missing", detail, phase === "validate" ? 400 : 403);
     }
     if (code === 4001 || status === 429) {
-        return hithinkError("rate_limited", `${detail}. Reduce request frequency and concurrency, then retry with exponential backoff (up to 3 attempts)`, 429);
+        const retryAdvice = message.startsWith("Global request rate limit exceeded")
+            ? "This upstream limit is shared across the account. Wait before retrying; reconnecting or sending concurrent retries will not reset it"
+            : "Reduce request frequency and concurrency, then retry with exponential backoff (up to 3 attempts)";
+        return hithinkError("rate_limited", `${detail}. ${retryAdvice}`, 429);
     }
     if (code === 4040) {
         return hithinkError("provider_error", requestId
@@ -522,9 +504,6 @@ function buildProviderError(status, code, payload, phase) {
     }
     return hithinkError("provider_error", detail, status >= 500 ? 502 : 503);
 }
-function readInteger(value) {
-    return typeof value === "number" && Number.isInteger(value) ? value : undefined;
-}
 function hithinkError(code, message, status) {
     return new ProviderRequestError(status, message, { code });
 }