@oomol-lab/open-connector 1.6.1 → 1.6.3

package/src/providers/linkfox/runtime.js

@@ -4,6 +4,7 @@ import { chuhaijiangOperations } from "./chuhaijiang-actions.js";
 import { normalizeChuhaijiang, searchChuhaijiangImage } from "./chuhaijiang-runtime.js";
 import { mercadoOperations } from "./mercado-actions.js";
 import { seerfarOperations } from "./seerfar-actions.js";
+import { sifOperations } from "./sif-actions.js";
 import { zhihuiyaOperations } from "./zhihuiya-actions.js";
 import { validateZhihuiyaInput } from "./zhihuiya-runtime.js";
 const zhihuiyaOperationsByName = new Map(zhihuiyaOperations.map(({ action, path }) => [action.name, { path }]));
@@ -32,6 +33,10 @@ const directOperations = {
             normalize: (payload) => requiredResponseRecord(payload, "LinkFox Seerfar response"),
         },
     ])),
+    ...Object.fromEntries(sifOperations.map(({ action, path }) => [
+        action.name,
+        { path, gatewayBusinessCodeOnly: true, normalize: normalizeSifResult },
+    ])),
     get_current_account: {
         path: "/account/currentByAPI",
         method: "GET",
@@ -299,10 +304,13 @@ export async function executeLinkfoxAction(actionName, input, apiKey, fetcher, p
     }
     const direct = directOperations[actionName];
     if (direct) {
+        if (direct.gatewayBusinessCodeOnly)
+            validateSifInput(actionName, input);
         const body = direct.buildBody ? direct.buildBody(input) : input;
         const payload = await requestLinkfoxPayload(direct.path, {
             method: direct.method ?? "POST",
             timeoutMs: direct.timeoutMs,
+            gatewayBusinessCodeOnly: direct.gatewayBusinessCodeOnly,
             ...((direct.method ?? "POST") === "POST" ? { body } : {}),
         }, apiKey, fetcher, "execute", false, parentSignal);
         return direct.normalize(payload);
@@ -313,6 +321,32 @@ export async function executeLinkfoxAction(actionName, input, apiKey, fetcher, p
     }
     return handler(input, { apiKey, fetcher, signal: parentSignal });
 }
+function validateSifInput(actionName, input) {
+    if (actionName === "list_sif_asin_keywords") {
+        const periodType = optionalString(input.timePieceType) ?? "latelyDay";
+        const periodValue = optionalString(input.timePieceValue);
+        if ((periodType === "month" || periodType === "week") && !periodValue) {
+            throw new ProviderRequestError(400, "timePieceValue is required for month or week periods");
+        }
+    }
+    const startDate = optionalString(input.startDate);
+    const endDate = optionalString(input.endDate);
+    if ((startDate && !endDate) || (!startDate && endDate)) {
+        throw new ProviderRequestError(400, "startDate and endDate must be provided together");
+    }
+    if ((startDate || endDate) && input.last7d !== false) {
+        throw new ProviderRequestError(400, "last7d must be false when a date range is provided");
+    }
+    if (startDate && endDate && startDate > endDate) {
+        throw new ProviderRequestError(400, "startDate must not be later than endDate");
+    }
+    if (actionName === "get_sif_asin_traffic_summary") {
+        const asins = optionalString(input.asins);
+        if (asins && asins.split(",").length > 10) {
+            throw new ProviderRequestError(400, "asins must contain at most 10 comma-separated ASINs");
+        }
+    }
+}
 function validateLinkfoxActionInput(actionName, input) {
     if (actionName === "search_amazon_by_image" && input.deliveryZip && input.countryOrAreaCode) {
         throw new ProviderRequestError(400, "deliveryZip and countryOrAreaCode cannot be used together");
@@ -422,7 +456,9 @@ async function requestLinkfoxPayload(path, options, apiKey, fetcher, phase = "ex
             signal,
         });
         const payload = await readJsonPayload(response);
-        const businessCode = readBusinessCode(payload);
+        const businessCode = options.gatewayBusinessCodeOnly
+            ? readGatewayBusinessCode(payload)
+            : readBusinessCode(payload);
         if (acceptCreditError && businessCode === 402)
             return payload;
         if (!response.ok || (businessCode !== undefined && businessCode !== 200)) {
@@ -482,6 +518,17 @@ function readBusinessCode(payload) {
     }
     return undefined;
 }
+function readGatewayBusinessCode(payload) {
+    const record = optionalRecord(payload);
+    for (const key of ["errcode", "errorCode"]) {
+        const value = record?.[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+        if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+            return Number(value);
+    }
+    return undefined;
+}
 function readErrorMessage(payload) {
     if (typeof payload === "string" && payload.trim()) {
         return payload.trim();
@@ -522,6 +569,28 @@ function normalizeDataList(payload) {
         costToken: readNumber(record.costToken),
     };
 }
+function normalizeSifResult(payload) {
+    const record = requireRecord(payload, "LinkFox returned an invalid SIF response");
+    const code = typeof record.code === "string" || typeof record.code === "number" ? String(record.code) : undefined;
+    if (code !== "1") {
+        throw new ProviderRequestError(502, readString(record.msg) ?? "LinkFox SIF returned an unsuccessful business response", record);
+    }
+    const data = readArray(record.data);
+    if (!data)
+        throw new ProviderRequestError(502, "LinkFox SIF response did not include data", record);
+    return {
+        ...record,
+        code,
+        msg: readString(record.msg) ?? null,
+        total: readInteger(record.total) ?? data.length,
+        data,
+        columns: readArray(record.columns) ?? [],
+        type: readString(record.type) ?? null,
+        title: readString(record.title) ?? null,
+        costTime: readInteger(record.costTime),
+        costToken: readNumber(record.costToken),
+    };
+}
 function normalizeVideoList(payload) {
     const record = requireRecord(payload, "LinkFox returned an invalid video response");
     const videos = readArray(record.videos) ?? readArray(record.data) ?? [];

package/src/providers/linkfox/seerfar-actions.js

@@ -2,11 +2,11 @@ import { s } from "../../core/json-schema.js";
 import { defineProviderAction } from "../../core/provider-definition.js";
 const literal = (description, value) => s.literal(value, { description });
 const strictObject = (description, properties, options) => s.object(description, properties, options ?? { required: Object.keys(properties) });
-function operation(name, path, usage, description, inputSchema, outputSchema) {
+function operation(name, operationType, path, usage, description, inputSchema, outputSchema) {
     return {
         path,
         usage,
-        action: defineProviderAction("linkfox", { name, description, inputSchema, outputSchema }),
+        action: defineProviderAction("linkfox", { name, operationType, description, inputSchema, outputSchema }),
     };
 }
 const pageSchema = s.object("Pagination and sorting.", {
@@ -119,7 +119,7 @@ const monthlyRevenueSchema = s.object("Monthly revenue range in RUB.", {
 });
 const dailySalesSchema = s.number("Average daily sales units.");
 export const seerfarOperations = [
-    operation("list_seerfar_ozon_category_products", "/seerfar/ozon/categorySearch", 15, "List Ozon category products and aggregate statistics through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("list_seerfar_ozon_category_products", "read", "/seerfar/ozon/categorySearch", 15, "List Ozon category products and aggregate statistics through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         categoryId: s.nonEmptyString("The Seerfar Ozon category ID; join category levels with underscores."),
         page: pageSchema,
         date: dateSchema,
@@ -147,7 +147,7 @@ export const seerfarOperations = [
         seasonalityAmplitude: s.optional(s.string("Seasonality strength.")),
         seasonalityCoef: s.optional(s.string("Seasonality phase.")),
     })),
-    operation("reverse_search_seerfar_ozon_keywords", "/seerfar/ozon/keywordBackSearch", 23, "Reverse-search Ozon keywords for SKU IDs through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("reverse_search_seerfar_ozon_keywords", "read", "/seerfar/ozon/keywordBackSearch", 23, "Reverse-search Ozon keywords for SKU IDs through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         skuIds: s.array("Up to 20 SKU IDs to reverse-search.", s.integer("An Ozon SKU ID."), {
             maxItems: 20,
         }),
@@ -199,7 +199,7 @@ export const seerfarOperations = [
         total: totalSchema2,
         data: dataSchema,
     })),
-    operation("mine_seerfar_ozon_keywords", "/seerfar/ozon/keywordMining", 23, "Mine Ozon keywords from a seed keyword through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("mine_seerfar_ozon_keywords", "read", "/seerfar/ozon/keywordMining", 23, "Mine Ozon keywords from a seed keyword through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         keyword: s.nonEmptyString("The seed keyword.", { maxLength: 1000 }),
         page: pageSchema2,
         matchType: matchTypeSchema,
@@ -232,7 +232,7 @@ export const seerfarOperations = [
         total: totalSchema2,
         data: dataSchema,
     })),
-    operation("search_seerfar_ozon_market_keywords", "/seerfar/ozon/marketKeywordSearch", 15, "Search Ozon market keywords through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("search_seerfar_ozon_market_keywords", "read", "/seerfar/ozon/marketKeywordSearch", 15, "Search Ozon market keywords through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         page: pageSchema2,
         keywords: s.array("Search keywords.", s.string("An array entry."), { maxItems: 1000 }),
         matchType: matchTypeSchema,
@@ -276,7 +276,7 @@ export const seerfarOperations = [
         total: totalSchema2,
         data: dataSchema,
     })),
-    operation("get_seerfar_ozon_product", "/seerfar/ozon/productDetailSearch", 5, "Get an Ozon product snapshot and sales history through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("get_seerfar_ozon_product", "read", "/seerfar/ozon/productDetailSearch", 5, "Get an Ozon product snapshot and sales history through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         sku: s.nonEmptyString("A single Ozon SKU as a string."),
         dateRange: {
             ...s.stringEnum("The sales statistics window; product metadata remains a current snapshot.", [
@@ -308,7 +308,7 @@ export const seerfarOperations = [
         salesTrendVOList: s.optional(s.array("Daily sales, revenue, price, stock and review history.", s.looseObject("A daily statistics record.", {}))),
         categoryRanks: s.optional(s.array("Historical category ranks.", s.looseObject("A category rank record.", {}))),
     })),
-    operation("search_seerfar_ozon_product_reports", "/seerfar/ozon/productReportSearch", 15, "Search Ozon product reports with commercial filters through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("search_seerfar_ozon_product_reports", "read", "/seerfar/ozon/productReportSearch", 15, "Search Ozon product reports with commercial filters through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         page: pageSchema2,
         skus: s.array("Up to 10 exact SKU IDs.", s.integer("An Ozon SKU ID."), { maxItems: 10 }),
         keywords: s.array("Search keywords.", s.string("An array entry.")),
@@ -405,7 +405,7 @@ export const seerfarOperations = [
         data: dataSchema,
         products: s.optional(productsSchema),
     })),
-    operation("list_seerfar_ozon_shop_products", "/seerfar/ozon/shopSearch", 15, "List Ozon shop products and aggregate statistics through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
+    operation("list_seerfar_ozon_shop_products", "read", "/seerfar/ozon/shopSearch", 15, "List Ozon shop products and aggregate statistics through LinkFox and Seerfar.", strictObject("Seerfar Ozon request parameters.", {
         id: s.integer("The seller ID; negative values identify Ozon-operated sellers."),
         page: pageSchema,
         uId: uIdSchema,

package/src/providers/linkfox/sif-actions.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderActionDefinition } from "../../core/provider-definition.ts";
+import type { ActionDefinition } from "../../core/types.ts";
+interface SifOperation {
+    path: string;
+    usage: number;
+    action: ProviderActionDefinition;
+}
+export declare const sifOperations: readonly SifOperation[];
+export declare const sifActions: readonly ActionDefinition[];
+export {};

package/src/providers/linkfox/sif-actions.js

@@ -0,0 +1,193 @@
+import { jsonSchema as s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+const sifCountries = ["US", "UK", "DE", "CA", "JP", "FR", "ES", "IT", "MX", "AU", "AE", "BR", "SA"];
+const summarySortFields = [
+    "totalKeywordNum",
+    "naturalKeywordNum",
+    "brandKeywordNum",
+    "vedioKeywordNum",
+    "acKeywordNum",
+    "erKeywordNum",
+    "trKeywordNum",
+    "sumScore",
+    "totalNfScore",
+    "totalSpSocre",
+    "totalBrandScore",
+    "totalVedioScore",
+    "totalAcScore",
+    "totalTrScore",
+    "totalErScore",
+];
+const keywordSummaryConditions = [
+    "nfPosition",
+    "isSpAd",
+    "isVedioAd",
+    "isBrandAd",
+    "isPPCAd",
+    "isSearchRecommend",
+    "acAd",
+    "totalPeriod.in",
+    "nfKeywordCnt.total",
+    "nfKeywordCnt.in",
+    "adKeywordCnt.total",
+    "adKeywordCnt.in",
+    "allSpKeywordCnt.total",
+    "allSpKeywordCnt.in",
+    "spKeywordCnt.total",
+    "spKeywordCnt.in",
+    "recSpKeywordCnt.total",
+    "recSpKeywordCnt.in",
+    "allSbKeywordCnt.total",
+    "allSbKeywordCnt.in",
+    "sbKeywordCnt.total",
+    "sbKeywordCnt.in",
+    "sbvKeywordCnt.total",
+    "sbvKeywordCnt.in",
+];
+const _asinKeywordConditionValues = [
+    "nfPosition",
+    "isSpAd",
+    "isBrandAd",
+    "isVedioAd",
+    "isAC",
+    "isAccurateKw",
+    "isAccurateTailKw",
+    "isPurchaseKw",
+    "isQualityKw",
+    "isStableKw",
+    "isLossKw",
+    "isInvalidKw",
+    "isMultiVariantKw",
+    "isSearchVolUpKw",
+    "isSearchVolDownKw",
+    "totalPeriod.in",
+    "nfKeywordCnt.total",
+    "nfKeywordCnt.in",
+    "adKeywordCnt.total",
+    "adKeywordCnt.in",
+    "allSpKeywordCnt.total",
+    "allSpKeywordCnt.in",
+    "spKeywordCnt.total",
+    "spKeywordCnt.in",
+    "recSpKeywordCnt.total",
+    "recSpKeywordCnt.in",
+    "allSbKeywordCnt.total",
+    "allSbKeywordCnt.in",
+    "sbKeywordCnt.total",
+    "sbKeywordCnt.in",
+    "sbvKeywordCnt.total",
+    "sbvKeywordCnt.in",
+];
+const _asinSummaryConditionValues = ["nf", "sp", "sb", "sbv", "ad", "acAd", "totalPeriod.in"];
+const countrySchema = s.optional(s.stringEnum("The Amazon marketplace code. LinkFox defaults to US when omitted.", sifCountries));
+const nullableInteger = (description) => s.nullable(s.integer(description));
+const nullableNumber = (description) => s.nullable(s.number(description));
+const nullableString = (description) => s.nullable(s.string(description));
+function resultSchema(description, recordDescription, extra = {}) {
+    return s.looseRequiredObject(description, {
+        code: s.string("The SIF business code; 1 indicates success."),
+        msg: nullableString("The SIF response message."),
+        total: s.integer("The number of records returned by this request.", { minimum: 0 }),
+        data: s.array("The SIF records returned by this request.", s.looseObject(recordDescription)),
+        columns: s.array("The LinkFox rendering-column definitions.", s.looseObject("A provider-defined rendering-column definition.")),
+        type: nullableString("The LinkFox rendering style when provided."),
+        title: nullableString("The result title when provided."),
+        costTime: nullableInteger("The upstream processing time in milliseconds."),
+        costToken: nullableNumber("The LinkFox token cost when provided."),
+        ...extra,
+    });
+}
+const asinKeywordsInputBase = s.object("Parameters for reverse-searching one ASIN's SIF keywords.", {
+    asin: s.nonEmptyString("The single Amazon ASIN to analyze.", { maxLength: 1000 }),
+    country: countrySchema,
+    keyword: s.optional(s.string("An optional localized keyword used to filter the result.", { maxLength: 1000 })),
+    timePieceType: s.optional(s.stringEnum("The analysis period type. LinkFox defaults to latelyDay.", ["latelyDay", "month", "week"])),
+    timePieceValue: s.optional(s.string("The period value: 7 or 30 for latelyDay, YYYY-MM for month, or the week-start date in YYYY-MM-DD format.", { maxLength: 1000 })),
+    conditions: s.optional(s.string("Comma-separated SIF keyword filters, including traffic-position, advertising, conversion, stability, and period-entry markers.", { maxLength: 1000 })),
+    sortBy: s.optional(s.stringEnum("The keyword sort field. Omit it to use SIF's system order.", [
+        "lastRank",
+        "adLastRank",
+        "updateTime",
+        "searchesRank",
+        "estSearchesNum",
+    ])),
+    desc: s.optional(s.boolean("Whether to sort descending. LinkFox defaults to true.")),
+    pageNum: s.optional(s.integer("The one-based result page. LinkFox defaults to 1.", { minimum: 1 })),
+    pageSize: s.optional(s.integer("The number of keyword records per page. LinkFox defaults to 100.", {
+        minimum: 10,
+        maximum: 100,
+    })),
+});
+const asinKeywordsInput = asinKeywordsInputBase;
+const dateRangeFields = {
+    last7d: s.optional(s.boolean("Whether to use the latest seven days. Set false to use startDate and endDate; LinkFox defaults to true.")),
+    startDate: s.optional(s.date("The period start date, used when last7d is false.")),
+    endDate: s.optional(s.date("The period end date, paired with startDate.")),
+};
+const asinSummaryInputBase = s.object("Parameters for summarizing SIF traffic sources by ASIN.", {
+    searchValue: s.nonEmptyString("One to ten comma-separated Amazon ASINs.", { maxLength: 1000 }),
+    country: countrySchema,
+    ...dateRangeFields,
+    conditions: s.optional(s.string("Comma-separated SIF filters: nf, sp, sb, sbv, ad, acAd, or totalPeriod.in.", {
+        maxLength: 1000,
+    })),
+    sortBy: s.optional(s.stringEnum("The ASIN traffic-summary sort field.", summarySortFields)),
+    pageNum: s.optional(s.integer("The one-based result page. LinkFox defaults to 1.", { minimum: 1 })),
+    pageSize: s.optional(s.integer("The number of ASIN summaries per page. LinkFox defaults to 10000.", {
+        minimum: 10,
+        maximum: 10_000,
+    })),
+    desc: s.optional(s.boolean("Whether to sort descending. LinkFox defaults to true.")),
+});
+const asinSummaryInput = asinSummaryInputBase;
+const keywordOverviewInputBase = s.object("Parameters for retrieving a SIF keyword overview.", {
+    keyword: s.nonEmptyString("The localized Amazon keyword to analyze.", { maxLength: 1000 }),
+    country: countrySchema,
+    ...dateRangeFields,
+});
+const keywordOverviewInput = keywordOverviewInputBase;
+const keywordSummaryInputBase = s.object("Parameters for summarizing competitor traffic sources for one keyword.", {
+    searchKeyword: s.nonEmptyString("The localized Amazon keyword to analyze.", {
+        maxLength: 1000,
+    }),
+    country: countrySchema,
+    asins: s.optional(s.string("An optional comma-separated ASIN filter.", { maxLength: 1000 })),
+    condition: s.optional(s.stringEnum("One SIF traffic or period filter, such as nfPosition, isSpAd, isBrandAd, isPPCAd, acAd, or totalPeriod.in.", keywordSummaryConditions)),
+    ...dateRangeFields,
+    sortBy: s.optional(s.stringEnum("The competitor traffic-summary sort field.", summarySortFields)),
+    pageNum: s.optional(s.integer("The one-based result page. LinkFox defaults to 1.", { minimum: 1 })),
+    pageSize: s.optional(s.integer("The number of competitor ASINs per page. LinkFox defaults to 100.", {
+        minimum: 10,
+        maximum: 100,
+    })),
+    desc: s.optional(s.boolean("Whether to sort descending. LinkFox defaults to true.")),
+});
+const keywordSummaryInput = keywordSummaryInputBase;
+function operation(name, path, description, inputSchema, outputSchema) {
+    return {
+        path,
+        usage: 9,
+        action: defineProviderAction("linkfox", {
+            name,
+            description,
+            operationType: "read",
+            inputSchema,
+            outputSchema,
+        }),
+    };
+}
+export const sifOperations = [
+    operation("list_sif_asin_keywords", "/sif/asinKeywords", "Reverse-search one Amazon ASIN's SIF traffic keywords, ranks, traffic shares, and conversion markers through LinkFox.", asinKeywordsInput, resultSchema("SIF keyword intelligence for one Amazon ASIN.", "A SIF keyword record with ranks, search volume, traffic shares, exposure scores, placements, and conversion markers.", {
+        isParentAsin: s.optional(s.boolean("Whether the queried ASIN is a parent ASIN.")),
+        hasVaiants: s.optional(s.boolean("Whether the queried product has variants.")),
+        abaCreateDateWeek: nullableString("The latest week represented by the ABA data."),
+    })),
+    operation("get_sif_asin_traffic_summary", "/sif/asinSummary", "Summarize natural, advertising, and recommendation traffic sources for up to ten Amazon ASINs through LinkFox and SIF.", asinSummaryInput, resultSchema("SIF traffic-source summaries for Amazon ASINs.", "A SIF ASIN summary with product context, current and previous exposure scores, traffic shares, keyword counts, entry or exit counts, and source markers.", {
+        isParentAsin: s.optional(s.boolean("Whether the search target is a parent ASIN.")),
+        variantsNum: nullableInteger("The number of variants with traffic keywords."),
+        noKeywordVariantsNum: nullableInteger("The number of variants without traffic keywords."),
+    })),
+    operation("get_sif_keyword_overview", "/sif/keywordOverview", "Get SIF search demand, supply-demand ratio, and advertising or recommendation competition for one Amazon keyword through LinkFox.", keywordOverviewInput, resultSchema("A SIF market-competition overview for one Amazon keyword.", "A SIF keyword overview with search volume, supply-demand ratio, product counts by traffic placement, tracked ASIN totals, and data-period timestamps.")),
+    operation("get_sif_keyword_traffic_summary", "/sif/keywordSummary", "Analyze competitor ASIN traffic shares and natural, advertising, or recommendation exposure for one Amazon keyword through LinkFox and SIF.", keywordSummaryInput, resultSchema("SIF competitor traffic-source summaries for one Amazon keyword.", "A SIF competitor record with product context, overall and queried-keyword exposure scores, traffic shares, and source markers.")),
+];
+export const sifActions = sifOperations.map(({ action }) => action);

package/src/providers/linkfox/zhihuiya-actions.js

@@ -23,12 +23,18 @@ function patentInput(extra = {}, maxLength) {
     ];
     return schema;
 }
-function operation(name, path, description, inputSchema, usage, perRecord = true) {
+function operation(name, operationType, path, description, inputSchema, usage, perRecord = true) {
     return {
         path: `/zhihuiya/${path}`,
         usage,
         perRecord,
-        action: defineProviderAction("linkfox", { name, description, inputSchema, outputSchema: patentOutput }),
+        action: defineProviderAction("linkfox", {
+            name,
+            operationType,
+            description,
+            inputSchema,
+            outputSchema: patentOutput,
+        }),
     };
 }
 const imageInput = strictObject("Search design or utility patents by image URL through Patsnap. Design models are 1 or 2; utility models are 3 or 4.", {
@@ -106,26 +112,26 @@ const queryInput = strictObject("Search patents using a Patsnap Analytics query.
     collapseOrderAuthority: s.optional(s.array("The authority priority order, used when collapseBy is AUTHORITY.", s.string("A patent authority code."))),
 });
 export const zhihuiyaOperations = [
-    operation("translate_zhihuiya_patent_abstracts", "abstractDataTranslated", "Get translated patent titles and abstracts through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
-    operation("get_zhihuiya_patent_abstract_images", "abstractImage", "Get patent abstract image URLs through LinkFox and Patsnap.", patentInput({}, 60000), 81),
-    operation("get_zhihuiya_patent_bibliography", "bibliography", "Get detailed patent bibliographic records through LinkFox and Patsnap.", patentInput({}, 60000), 81),
-    operation("get_zhihuiya_patent_claims", "claimData", "Get original patent claims through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }, 60000), 81),
-    operation("translate_zhihuiya_patent_claims", "claimDataTranslated", "Get translated patent claims through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
-    operation("get_zhihuiya_patent_descriptions", "descriptionData", "Get original patent description sections through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }, 60000), 81),
-    operation("translate_zhihuiya_patent_descriptions", "descriptionDataTranslated", "Get translated patent descriptions through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
-    operation("get_zhihuiya_patent_fulltext_images", "fulltextImage", "Get patent full-text image URLs through LinkFox and Patsnap.", patentInput({
+    operation("translate_zhihuiya_patent_abstracts", "read", "abstractDataTranslated", "Get translated patent titles and abstracts through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
+    operation("get_zhihuiya_patent_abstract_images", "read", "abstractImage", "Get patent abstract image URLs through LinkFox and Patsnap.", patentInput({}, 60000), 81),
+    operation("get_zhihuiya_patent_bibliography", "read", "bibliography", "Get detailed patent bibliographic records through LinkFox and Patsnap.", patentInput({}, 60000), 81),
+    operation("get_zhihuiya_patent_claims", "read", "claimData", "Get original patent claims through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }, 60000), 81),
+    operation("translate_zhihuiya_patent_claims", "read", "claimDataTranslated", "Get translated patent claims through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
+    operation("get_zhihuiya_patent_descriptions", "read", "descriptionData", "Get original patent description sections through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }, 60000), 81),
+    operation("translate_zhihuiya_patent_descriptions", "read", "descriptionDataTranslated", "Get translated patent descriptions through LinkFox and Patsnap.", patentInput({ replaceByRelated: replacement, lang: translationLanguage }, 60000), 81),
+    operation("get_zhihuiya_patent_fulltext_images", "read", "fulltextImage", "Get patent full-text image URLs through LinkFox and Patsnap.", patentInput({
         limit: s.optional(s.string("The number of images to return, as a string. Maximum 100; default: 100.", {
             maxLength: 1000,
         })),
         offset: s.optional(s.string("The image offset, as a string.", { maxLength: 1000 })),
     }, 1000), 81, false),
-    operation("get_zhihuiya_patent_legal_status", "legalStatus", "Get patent legal statuses and events through LinkFox and Patsnap.", patentInput({}, 60000), 81),
-    operation("get_zhihuiya_patent_cited_by", "patentCited", "Get patents that cite the specified patents and citation counts through LinkFox and Patsnap.", patentInput({}, 60000), 81),
-    operation("get_zhihuiya_patent_families", "patentFamily", "Get simple, INPADOC, and Patsnap patent families through LinkFox.", patentInput({}, 60000), 81),
-    operation("get_zhihuiya_patent_citations", "patentForwardCitation", "Get patent and non-patent documents cited by the specified patents through LinkFox and Patsnap.", patentInput({}, 60000), 81),
-    operation("search_zhihuiya_patents_by_image", "patentImageSearch", "Search design and utility patents by image with filters and pagination through LinkFox and Patsnap.", imageInput, 81, false),
-    operation("get_zhihuiya_patent_pdfs", "pdfData", "Get patent PDF download URLs through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }), 81),
-    operation("search_zhihuiya_patents", "querySearchPatent", "Search patents with Analytics expressions, deduplication, sorting, and pagination through LinkFox and Patsnap.", queryInput, 3),
-    operation("get_zhihuiya_patent_simple_bibliography", "simpleBibliography", "Get compact patent bibliographic records through LinkFox and Patsnap.", patentInput(), 81),
+    operation("get_zhihuiya_patent_legal_status", "read", "legalStatus", "Get patent legal statuses and events through LinkFox and Patsnap.", patentInput({}, 60000), 81),
+    operation("get_zhihuiya_patent_cited_by", "read", "patentCited", "Get patents that cite the specified patents and citation counts through LinkFox and Patsnap.", patentInput({}, 60000), 81),
+    operation("get_zhihuiya_patent_families", "read", "patentFamily", "Get simple, INPADOC, and Patsnap patent families through LinkFox.", patentInput({}, 60000), 81),
+    operation("get_zhihuiya_patent_citations", "read", "patentForwardCitation", "Get patent and non-patent documents cited by the specified patents through LinkFox and Patsnap.", patentInput({}, 60000), 81),
+    operation("search_zhihuiya_patents_by_image", "read", "patentImageSearch", "Search design and utility patents by image with filters and pagination through LinkFox and Patsnap.", imageInput, 81, false),
+    operation("get_zhihuiya_patent_pdfs", "read", "pdfData", "Get patent PDF download URLs through LinkFox and Patsnap.", patentInput({ replaceByRelated: stringReplacement }), 81),
+    operation("search_zhihuiya_patents", "read", "querySearchPatent", "Search patents with Analytics expressions, deduplication, sorting, and pagination through LinkFox and Patsnap.", queryInput, 3),
+    operation("get_zhihuiya_patent_simple_bibliography", "read", "simpleBibliography", "Get compact patent bibliographic records through LinkFox and Patsnap.", patentInput(), 81),
 ];
 export const zhihuiyaActions = zhihuiyaOperations.map(({ action }) => action);

package/src/providers/linkhut/actions.js

@@ -58,6 +58,7 @@ function action(input) {
 export const linkhutActions = [
     action({
         name: "add_bookmark",
+        operationType: "write",
         description: "Create a new bookmark in Linkhut without replacing an existing bookmark.",
         requiredScopes: ["posts:write"],
         inputSchema: bookmarkMutationInput,
@@ -65,6 +66,7 @@ export const linkhutActions = [
     }),
     action({
         name: "update_bookmark",
+        operationType: "write",
         description: "Update an existing Linkhut bookmark by URL.",
         requiredScopes: ["posts:write"],
         inputSchema: bookmarkMutationInput,
@@ -72,6 +74,7 @@ export const linkhutActions = [
     }),
     action({
         name: "delete_bookmark",
+        operationType: "destructive",
         description: "Delete a Linkhut bookmark by URL.",
         requiredScopes: ["posts:write"],
         inputSchema: s.object("The input payload for this action.", {
@@ -81,6 +84,7 @@ export const linkhutActions = [
     }),
     action({
         name: "get_bookmarks",
+        operationType: "read",
         description: "List Linkhut bookmarks using the official bookmark filters.",
         requiredScopes: ["posts:read"],
         inputSchema: bookmarkFilterInput,
@@ -90,6 +94,7 @@ export const linkhutActions = [
     }),
     action({
         name: "get_all_tags",
+        operationType: "read",
         description: "List all Linkhut tags with their bookmark counts.",
         requiredScopes: ["tags:read"],
         inputSchema: s.object({}, { description: "The input payload for this action." }),

package/src/providers/listmonk/executors.d.ts

@@ -0,0 +1,4 @@
+import type { CredentialValidators, ProviderExecutors, ProviderProxyExecutor } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const proxy: ProviderProxyExecutor;
+export declare const credentialValidators: CredentialValidators;

package/src/providers/listmonk/executors.js

@@ -0,0 +1,43 @@
+import { isPrivateNetworkAccessAllowed } from "../../core/request.js";
+import { combineProviderActionHandlers, createProviderFetch, defineProviderExecutors, defineProviderProxy, requireApiKeyCredential, } from "../provider-runtime.js";
+import { listmonkActionHandlers, listmonkAuthorizationHeader, resolveListmonkApiUser, resolveListmonkBaseUrl, validateListmonkCredential, } from "./runtime.js";
+const service = "listmonk";
+export const executors = defineProviderExecutors({
+    service,
+    handlers: combineProviderActionHandlers(service, listmonkActionHandlers),
+    allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+    async createContext(context, fetcher) {
+        const credential = await requireApiKeyCredential(context, service);
+        return {
+            apiUser: resolveListmonkApiUser(credential),
+            apiKey: credential.apiKey,
+            baseUrl: resolveListmonkBaseUrl(credential),
+            fetcher,
+            signal: context.signal,
+        };
+    },
+});
+// Hand-written auth: listmonk's `token <api_user>:<token>` header combines two
+// credential fields, which none of the declarative proxy auth modes can express.
+export const proxy = defineProviderProxy({
+    service,
+    async baseUrl(context) {
+        const credential = await requireApiKeyCredential(context, service);
+        return `${resolveListmonkBaseUrl(credential)}/api/`;
+    },
+    auth: { type: "none" },
+    async customizeRequest({ context, headers }) {
+        const credential = await requireApiKeyCredential(context, service);
+        headers.set("authorization", listmonkAuthorizationHeader(resolveListmonkApiUser(credential), credential.apiKey));
+        if (!headers.has("accept"))
+            headers.set("accept", "application/json");
+    },
+    allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+});
+export const credentialValidators = {
+    apiKey(input, { fetcher, signal }) {
+        // Re-guard so validating a private instance baseUrl follows the deployment opt-in.
+        const guardedFetcher = createProviderFetch({ fetch: fetcher, allowPrivateNetwork: isPrivateNetworkAccessAllowed });
+        return validateListmonkCredential(input, guardedFetcher, signal);
+    },
+};

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

@@ -0,0 +1,36 @@
+import type { CredentialValidationResult } from "../../core/types.ts";
+import type { ProviderActionHandlerSubset, ProviderFetch } from "../provider-runtime.ts";
+export interface ListmonkActionContext {
+    apiUser: string;
+    apiKey: string;
+    baseUrl: string;
+    fetcher: ProviderFetch;
+    signal?: AbortSignal;
+}
+export type ListmonkActionHandler = (input: Record<string, unknown>, context: ListmonkActionContext) => Promise<unknown>;
+interface ListmonkCredentialInput {
+    values?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Build the listmonk API-user Authorization header, `token <api_user>:<token>`.
+ */
+export declare function listmonkAuthorizationHeader(apiUser: string, apiKey: string): string;
+/**
+ * Resolve the instance root URL from validator metadata or the raw credential field.
+ */
+export declare function resolveListmonkBaseUrl(input: ListmonkCredentialInput): string;
+/**
+ * Resolve the API username from the credential fields.
+ */
+export declare function resolveListmonkApiUser(input: ListmonkCredentialInput): string;
+export declare const listmonkActionHandlers: ProviderActionHandlerSubset<"listmonk", ListmonkActionHandler>;
+/**
+ * Validate a listmonk API user by reading its own profile. The validator
+ * fetcher must already be re-guarded with the private-network opt-in.
+ */
+export declare function validateListmonkCredential(input: {
+    apiKey: string;
+    values: Record<string, string>;
+}, fetcher: ProviderFetch, signal?: AbortSignal): Promise<CredentialValidationResult>;
+export {};