@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/providers/keepa/actions.js

@@ -1,7 +1,9 @@
 import { s } from "../../core/json-schema.js";
 import { defineProviderAction } from "../../core/provider-definition.js";
+import { keepaDealAttributeNames } from "./deal-attributes.js";
 const service = "keepa";
 export const keepaMarketplaces = ["US", "GB", "DE", "FR", "JP", "CA", "IT", "ES", "IN", "MX", "BR"];
+const keepaStandardMarketplaces = keepaMarketplaces.filter((marketplace) => marketplace !== "BR");
 export const keepaHistoryTypes = [
     "AMAZON",
     "NEW",
@@ -51,29 +53,55 @@ export const keepaDealPriceTypes = [
     "LIGHTNING_DEAL",
     "WAREHOUSE",
     "NEW_FBA",
+    "BUY_BOX_SHIPPING",
     "USED_NEW_SHIPPING",
     "USED_VERY_GOOD_SHIPPING",
     "USED_GOOD_SHIPPING",
     "USED_ACCEPTABLE_SHIPPING",
-    "COLLECTIBLE_NEW_SHIPPING",
-    "COLLECTIBLE_VERY_GOOD_SHIPPING",
-    "COLLECTIBLE_GOOD_SHIPPING",
-    "COLLECTIBLE_ACCEPTABLE_SHIPPING",
     "REFURBISHED_SHIPPING",
     "BUY_BOX_USED_SHIPPING",
     "PRIME_EXCL",
 ];
 const marketplaceSchema = s.stringEnum("Amazon marketplace code using Keepa's official AmazonLocale names.", keepaMarketplaces);
-const asinSchema = s.stringPattern("^[A-Za-z0-9]{10}$", {
-    description: "A 10-character Amazon ASIN containing only ASCII letters or digits.",
+const standardMarketplaceSchema = s.stringEnum("Amazon marketplace supported by this Keepa endpoint (Brazil is unavailable).", keepaStandardMarketplaces);
+const asinSchema = s.string("A 10-character Amazon ASIN.", {
+    minLength: 10,
+    maxLength: 10,
+    pattern: "^[A-Za-z0-9]{10}$",
 });
 const asinsSchema = s.array("Amazon ASINs to request.", asinSchema, {
     minItems: 1,
     maxItems: 100,
 });
+const codesSchema = s.array("UPC, EAN, GTIN, or ISBN-13 codes; keep leading zeroes.", s.string("One numeric product code, kept as a string.", { pattern: "^[0-9]{8,14}$" }), { minItems: 1, maxItems: 100 });
+const statsRangeSchema = s.requiredObject("UTC statistics interval.", {
+    start: s.anyOf("Interval start, as ISO 8601 UTC text or Unix milliseconds.", [
+        s.dateTime("ISO 8601 UTC start time."),
+        s.nonNegativeInteger("Unix milliseconds at interval start."),
+    ]),
+    end: s.anyOf("Interval end, as ISO 8601 UTC text or Unix milliseconds.", [
+        s.dateTime("ISO 8601 UTC end time."),
+        s.nonNegativeInteger("Unix milliseconds at interval end."),
+    ]),
+});
+const windowInputFields = {
+    offset: s.nonNegativeInteger("Zero-based offset into this response's full upstream list."),
+    limit: s.nullable(s.positiveInteger("Maximum entries returned; null returns all remaining entries.")),
+};
+const windowOutputFields = {
+    totalAvailable: s.nonNegativeInteger("Number of entries in this upstream response."),
+    returnedCount: s.nonNegativeInteger("Number of entries in this response window."),
+    hasMore: s.boolean("Whether this upstream response contains more entries after the window."),
+    nextOffset: s.nullable(s.nonNegativeInteger("Next local offset, when more entries exist.")),
+};
 const productRequestOptionalFields = {
+    codes: codesSchema,
+    codeLimit: s.positiveInteger("Maximum products returned for each product code."),
     statsDays: s.positiveInteger("Number of recent days used for Keepa summary statistics at no additional token cost."),
-    updateHours: s.nonNegativeInteger("Refresh data when Keepa's stored product data is older than this many hours; zero may consume an extra token per product."),
+    statsRange: statsRangeSchema,
+    updateHours: s.integer("Refresh when older than these hours; zero forces refresh and -1 disables refresh.", {
+        minimum: -1,
+    }),
     offers: s.integer("Number of marketplace offers to include; values from 20 through 100 may increase token cost and limit the request to 20 ASINs.", {
         minimum: 20,
         maximum: 100,
@@ -81,18 +109,24 @@ const productRequestOptionalFields = {
     onlyLiveOffers: s.boolean("Whether to omit historical offers when offers are requested, reducing response size."),
     includeBuyBox: s.boolean("Whether to include Keepa buy box data; this may consume two additional tokens per product when offers are not requested."),
     includeRating: s.boolean("Whether to include existing rating and review-count history in the product payload."),
+    includeVideos: s.boolean("Whether to include existing product video metadata."),
+    includeAPlus: s.boolean("Whether to include existing A+ content."),
+    includeStock: s.boolean("Whether to include stock history with requested offers; may cost extra tokens."),
+    includeHistoricalVariations: s.boolean("Whether to include historical and out-of-stock variations; may cost extra tokens."),
 };
-const responseMetaSchema = s.object("Keepa request and token-budget metadata.", {
-    timestamp: s.nullableInteger("Keepa server response time in Unix epoch milliseconds."),
-    tokensLeft: s.nullableInteger("Tokens remaining after this request."),
-    refillInMs: s.nullableInteger("Milliseconds until Keepa next refills tokens."),
-    refillRatePerMinute: s.nullableInteger("Number of Keepa tokens refilled per minute."),
-    tokensConsumed: s.nullableInteger("Tokens consumed by this request."),
-    processingTimeMs: s.nullableInteger("Server-side processing time in milliseconds."),
+const responseMetaSchema = s.requiredObject("Keepa request and token-budget metadata.", {
+    timestamp: s.nullable(s.integer("Keepa server response time in Unix epoch milliseconds.")),
+    tokensLeft: s.nullable(s.integer("Tokens remaining after this request.")),
+    refillInMs: s.nullable(s.integer("Milliseconds until Keepa next refills tokens.")),
+    refillRatePerMinute: s.nullable(s.integer("Number of Keepa tokens refilled per minute.")),
+    tokensConsumed: s.nullable(s.integer("Tokens consumed by this request.")),
+    processingTimeMs: s.nullable(s.integer("Server-side processing time in milliseconds.")),
 });
+const nullableStringSchema = (description) => s.nullable(s.string(description));
+const nullableIntegerSchema = (description) => s.nullable(s.integer(description));
 const namedIntegerValuesSchema = s.record("Values keyed by official Keepa Product.CsvType name.", s.nullable(s.integer("A Keepa price, rank, count, rating, or metadata value; price values use the marketplace's smallest currency unit.")));
 const namedBooleanValuesSchema = s.record("Boolean values keyed by official Keepa Product.CsvType name.", s.boolean("A Keepa statistic flag."));
-const productStatsSchema = s.object("Named Keepa product statistics.", {
+const productStatsSchema = s.requiredObject("Named Keepa product statistics.", {
     current: namedIntegerValuesSchema,
     average: namedIntegerValuesSchema,
     average30Days: namedIntegerValuesSchema,
@@ -104,37 +138,37 @@ const productStatsSchema = s.object("Named Keepa product statistics.", {
     isLowest90Days: namedBooleanValuesSchema,
     raw: s.looseObject("The complete Keepa stats object."),
 });
-const productSnapshotSchema = s.object("A normalized Keepa product snapshot.", {
+const productSnapshotSchema = s.requiredObject("A normalized Keepa product snapshot.", {
     asin: s.string("Amazon ASIN."),
-    domainId: s.nullableInteger("Keepa Amazon locale identifier."),
-    title: s.nullableString("Amazon product title."),
-    brand: s.nullableString("Product brand."),
-    manufacturer: s.nullableString("Product manufacturer."),
-    productGroup: s.nullableString("Amazon product group."),
-    parentAsin: s.nullableString("Parent ASIN when this product is a variation."),
-    rootCategory: s.nullableInteger("Root Amazon category node identifier."),
+    domainId: nullableIntegerSchema("Keepa Amazon locale identifier."),
+    title: nullableStringSchema("Amazon product title."),
+    brand: nullableStringSchema("Product brand."),
+    manufacturer: nullableStringSchema("Product manufacturer."),
+    productGroup: nullableStringSchema("Amazon product group."),
+    parentAsin: nullableStringSchema("Parent ASIN when this product is a variation."),
+    rootCategory: nullableIntegerSchema("Root Amazon category node identifier."),
     categories: s.array("Amazon category node identifiers assigned to the product.", s.integer("One Amazon category node identifier.")),
     imageUrls: s.array("Resolved Amazon image URLs derived from Keepa image metadata.", s.string("One Amazon media image URL.")),
-    monthlySold: s.nullableInteger("Estimated monthly sold count when available."),
-    lastUpdate: s.nullableInteger("Last product update in Keepa Time minutes."),
+    monthlySold: nullableIntegerSchema("Estimated monthly sold count when available."),
+    lastUpdate: nullableIntegerSchema("Last product update in Keepa Time minutes."),
     stats: s.nullable(productStatsSchema),
     raw: s.looseObject("The complete Keepa product object."),
 });
-const productSnapshotOutputSchema = s.actionOutput({
+const productSnapshotOutputSchema = s.requiredObject("Keepa product snapshot response.", {
     marketplace: marketplaceSchema,
     priceValuesUseMinorUnits: s.literal(true, {
         description: "Whether price integers remain in the marketplace's smallest currency unit.",
     }),
     products: s.array("Products returned by Keepa.", productSnapshotSchema),
     meta: responseMetaSchema,
-}, "Keepa product snapshot response.");
-const historyPointSchema = s.object("One normalized Keepa history data point.", {
+});
+const historyPointSchema = s.requiredObject("One normalized Keepa history data point.", {
     keepaTime: s.integer("Original Keepa Time value in minutes."),
     timestamp: s.dateTime("UTC timestamp converted from Keepa Time."),
     value: s.integer("History value; price values use the marketplace's smallest currency unit and -1 represents no offer."),
-    shipping: s.nullableInteger("Shipping amount in the marketplace's smallest currency unit when this history type records it separately."),
+    shipping: s.nullable(s.integer("Shipping amount in the marketplace's smallest currency unit when this history type records it separately.")),
 });
-const historySeriesSchema = s.object("One named Keepa product history series.", {
+const historySeriesSchema = s.requiredObject("One named Keepa product history series.", {
     type: s.stringEnum("Official Keepa Product.CsvType name.", keepaHistoryTypes),
     index: s.integer("Official Keepa Product.CsvType array index."),
     unit: s.stringEnum("Unit interpretation for values in this series; lower sales-rank values indicate better rank.", [
@@ -147,57 +181,47 @@ const historySeriesSchema = s.object("One named Keepa product history series.",
     includesShipping: s.boolean("Whether each raw point contains a separate shipping value after the main value."),
     points: s.array("Chronological history points.", historyPointSchema),
 });
-const monthlySoldHistoryPointSchema = s.object("One historical Amazon bought-in-past-month value.", {
+const monthlySoldHistoryPointSchema = s.requiredObject("One historical Amazon bought-in-past-month value.", {
     keepaTime: s.integer("Original Keepa Time value in minutes."),
     timestamp: s.dateTime("UTC timestamp converted from Keepa Time."),
     value: s.integer("Amazon's bought-in-past-month value observed by Keepa; this is not a sales estimate."),
 });
-const couponHistoryPointSchema = s.object("One historical Keepa coupon observation.", {
+const couponHistoryPointSchema = s.requiredObject("One historical Keepa coupon observation.", {
     keepaTime: s.integer("Original Keepa Time value in minutes."),
     timestamp: s.dateTime("UTC timestamp converted from Keepa Time."),
     oneTimeCoupon: s.integer("One-time coupon discount: zero means unavailable, positive values use the marketplace's smallest currency unit, and negative values are percentage discounts."),
     subscribeAndSaveCoupon: s.integer("Subscribe-and-Save coupon discount: zero means unavailable, positive values use the marketplace's smallest currency unit, and negative values are percentage discounts."),
 });
-const salesRankHistorySchema = s.object("One Amazon subcategory sales-rank history.", {
+const salesRankHistorySchema = s.requiredObject("One Amazon subcategory sales-rank history.", {
     categoryId: s.integer("Amazon subcategory node ID."),
-    points: s.array("Chronological sales-rank observations; lower values indicate better rank.", s.object("One historical sales-rank observation.", {
+    points: s.array("Chronological sales-rank observations; lower values indicate better rank.", s.requiredObject("One historical sales-rank observation.", {
         keepaTime: s.integer("Original Keepa Time value in minutes."),
         timestamp: s.dateTime("UTC timestamp converted from Keepa Time."),
         value: s.integer("Amazon sales rank; lower values indicate better rank."),
     })),
 });
-const productHistorySchema = s.object("Normalized Keepa history for one product.", {
+const productHistorySchema = s.requiredObject("Normalized Keepa history for one product.", {
     asin: s.string("Amazon ASIN."),
-    title: s.nullableString("Amazon product title."),
-    brand: s.nullableString("Product brand."),
+    title: nullableStringSchema("Amazon product title."),
+    brand: nullableStringSchema("Product brand."),
     series: s.array("Named Keepa history series.", historySeriesSchema),
     monthlySoldHistory: s.array("Historical Amazon bought-in-past-month values returned by Keepa.", monthlySoldHistoryPointSchema),
     couponHistory: s.array("Historical coupon observations returned by Keepa.", couponHistoryPointSchema),
     salesRankHistory: s.array("Sales-rank histories grouped by Amazon subcategory.", salesRankHistorySchema),
     raw: s.looseObject("The complete Keepa product object including raw history arrays."),
 });
-const productHistoryOutputSchema = s.actionOutput({
+const productHistoryOutputSchema = s.requiredObject("Keepa product history response.", {
     marketplace: marketplaceSchema,
     priceValuesUseMinorUnits: s.literal(true, {
         description: "Whether price integers remain in the marketplace's smallest currency unit.",
     }),
     products: s.array("Products and normalized histories returned by Keepa.", productHistorySchema),
     meta: responseMetaSchema,
-}, "Keepa product history response.");
-const productFinderSortRuleSchema = {
-    type: "array",
-    prefixItems: [
-        s.nonEmptyString("Official Product Finder field name used for sorting."),
-        s.stringEnum("Sort direction.", ["asc", "desc"]),
-    ],
-    items: false,
-    minItems: 2,
-    maxItems: 2,
-    description: "One official Keepa Product Finder sort rule.",
-};
-const productFinderSortSchema = s.array("Product Finder sort rules in priority order.", productFinderSortRuleSchema, {
-    minItems: 1,
 });
+const productFinderSortSchema = s.array("Product Finder sort rules in priority order.", s.tuple([
+    s.nonEmptyString("Official Product Finder field name used for sorting."),
+    s.stringEnum("Sort direction.", ["asc", "desc"]),
+], { description: "One official Keepa Product Finder sort rule." }), { minItems: 1 });
 const productFinderFiltersSchema = s.looseObject("Official Keepa ProductFinderRequest fields. Unknown official fields are preserved for forward compatibility.", {
     title: s.nonEmptyString("Case-insensitive product title search text."),
     brand: s.stringArray("Brands to include.", {
@@ -248,50 +272,46 @@ const productFinderFiltersSchema = s.looseObject("Official Keepa ProductFinderRe
     hasMainVideo: s.boolean("Whether products must include a main video."),
     sort: productFinderSortSchema,
     page: s.nonNegativeInteger("Zero-based Product Finder result page."),
-    perPage: s.integer("Number of ASINs requested per Product Finder page.", {
-        minimum: 1,
+    perPage: s.integer("Number of ASINs requested per Product Finder page, from 50 to 10000.", {
+        minimum: 50,
+        maximum: 10_000,
     }),
 });
 const categorySchema = s.looseObject("One category object returned by Keepa.", {
-    catId: s.nullableInteger("Amazon category node identifier."),
-    domainId: s.nullableInteger("Keepa Amazon locale identifier."),
-    name: s.nullableString("Amazon category name."),
-    parent: s.nullableInteger("Parent category node identifier."),
+    catId: nullableIntegerSchema("Amazon category node identifier."),
+    domainId: nullableIntegerSchema("Keepa Amazon locale identifier."),
+    name: nullableStringSchema("Amazon category name."),
+    parent: nullableIntegerSchema("Parent category node identifier."),
     children: s.nullable(s.array("Child category node identifiers.", s.integer("One child category node identifier."))),
-    productCount: s.nullableInteger("Estimated product count."),
-    sellerCount: s.nullableInteger("Estimated distinct seller count."),
-});
-const dealRangeSchema = {
-    type: "array",
-    prefixItems: [
-        s.integer("Range lower bound."),
-        s.integer("Range upper bound; some Keepa ranges accept -1 as an open upper bound."),
-    ],
-    items: false,
-    minItems: 2,
-    maxItems: 2,
-    description: "Inclusive two-value range.",
-};
+    productCount: nullableIntegerSchema("Estimated product count."),
+    sellerCount: nullableIntegerSchema("Estimated distinct seller count."),
+});
+const dealRangeSchema = s.tuple([
+    s.integer("Range lower bound."),
+    s.integer("Range upper bound; some Keepa ranges accept -1 as an open upper bound."),
+], { description: "Inclusive two-value range." });
 const getTokenStatusAction = defineProviderAction(service, {
     name: "get_token_status",
     operationType: "read",
     description: "Retrieve Keepa token availability and refill information without consuming tokens.",
     requiredScopes: [],
-    inputSchema: s.actionInput({}, [], "Input for retrieving Keepa token status."),
-    outputSchema: s.actionOutput({
+    inputSchema: s.requiredObject("Input for retrieving Keepa token status.", {}),
+    outputSchema: s.requiredObject("Current Keepa token status.", {
         meta: responseMetaSchema,
-    }, "Current Keepa token status."),
+    }),
 });
 const getProductSnapshotAction = defineProviderAction(service, {
     name: "get_product_snapshot",
     operationType: "read",
     description: "Retrieve current Keepa product metadata and named statistics for one or more Amazon ASINs.",
     requiredScopes: [],
-    inputSchema: withProductRequestRules(s.actionInput({
+    inputSchema: s.object("Input for retrieving Keepa product snapshots.", {
         marketplace: marketplaceSchema,
         asins: asinsSchema,
         ...productRequestOptionalFields,
-    }, ["marketplace", "asins"], "Input for retrieving Keepa product snapshots.")),
+    }, {
+        optional: ["asins", ...Object.keys(productRequestOptionalFields)],
+    }),
     outputSchema: productSnapshotOutputSchema,
 });
 const getProductHistoryAction = defineProviderAction(service, {
@@ -299,13 +319,15 @@ const getProductHistoryAction = defineProviderAction(service, {
     operationType: "read",
     description: "Retrieve named Keepa price, rank, offer-count, rating, review, monthly-sales, and coupon history for Amazon ASINs.",
     requiredScopes: [],
-    inputSchema: withProductRequestRules(s.actionInput({
+    inputSchema: s.object("Input for retrieving Keepa product history.", {
         marketplace: marketplaceSchema,
         asins: asinsSchema,
         days: s.positiveInteger("Limit all returned history to the most recent number of 24-hour periods."),
         historyTypes: s.array("Keepa CSV history series to include in `series`; this does not suppress monthlySoldHistory, couponHistory, or salesRankHistory when Keepa returns them.", s.stringEnum("One official Keepa Product.CsvType name.", keepaHistoryTypes), { minItems: 1 }),
         ...productRequestOptionalFields,
-    }, ["marketplace", "asins"], "Input for retrieving Keepa product history.")),
+    }, {
+        optional: ["asins", "days", "historyTypes", ...Object.keys(productRequestOptionalFields)],
+    }),
     outputSchema: productHistoryOutputSchema,
 });
 const findProductsAction = defineProviderAction(service, {
@@ -313,62 +335,79 @@ const findProductsAction = defineProviderAction(service, {
     operationType: "read",
     description: "Find Amazon ASINs with Keepa Product Finder filters using official ProductFinderRequest field names.",
     requiredScopes: [],
-    inputSchema: s.actionInput({
+    inputSchema: s.object("Input for finding products in the Keepa catalog.", {
         marketplace: marketplaceSchema,
         filters: productFinderFiltersSchema,
-    }, ["marketplace", "filters"], "Input for finding products in the Keepa catalog."),
-    outputSchema: s.actionOutput({
+        includeSearchInsights: s.boolean("Include charged, query-wide Search Insights statistics."),
+    }, { optional: ["includeSearchInsights"] }),
+    outputSchema: s.requiredObject("Keepa Product Finder results.", {
         marketplace: marketplaceSchema,
         asins: s.array("Matching Amazon ASINs.", s.string("One Amazon ASIN.")),
-        totalResults: s.nullableInteger("Estimated total number of matching products."),
+        totalResults: s.nullable(s.integer("Estimated total number of matching products.")),
+        searchInsights: s.nullable(s.looseObject("Query-wide Search Insights returned when requested.")),
         meta: responseMetaSchema,
-    }, "Keepa Product Finder results."),
+    }),
 });
 const searchCategoriesAction = defineProviderAction(service, {
     name: "search_categories",
     operationType: "read",
     description: "Search Keepa Amazon categories by name so category IDs can be used in product and best-seller queries.",
     requiredScopes: [],
-    inputSchema: s.actionInput({
-        marketplace: marketplaceSchema,
+    inputSchema: s.object("Input for searching Keepa categories.", {
+        marketplace: standardMarketplaceSchema,
         term: s.nonEmptyString("Space-separated category keywords; each keyword must contain at least three characters."),
         includeParents: s.boolean("Whether Keepa should include the parent tree for each category."),
-    }, ["marketplace", "term"], "Input for searching Keepa categories."),
-    outputSchema: s.actionOutput({
-        marketplace: marketplaceSchema,
+    }, { optional: ["includeParents"] }),
+    outputSchema: s.requiredObject("Keepa category search results.", {
+        marketplace: standardMarketplaceSchema,
         categories: s.array("Matching categories.", categorySchema),
         categoryParents: s.array("Parent categories returned when requested.", categorySchema),
         meta: responseMetaSchema,
-    }, "Keepa category search results."),
+    }),
 });
 const getBestSellersAction = defineProviderAction(service, {
     name: "get_best_sellers",
     operationType: "read",
     description: "Retrieve Keepa's ordered Amazon best-seller ASIN list for a category node or website display group.",
     requiredScopes: [],
-    inputSchema: s.actionInput({
-        marketplace: marketplaceSchema,
+    inputSchema: s.object("Input for retrieving Keepa best sellers.", {
+        marketplace: standardMarketplaceSchema,
         category: s.anyOf("Amazon category node ID or Keepa website display group name.", [
             s.nonNegativeInteger("Amazon category node ID."),
             s.nonEmptyString("Keepa website display group name."),
         ]),
-    }, ["marketplace", "category"], "Input for retrieving Keepa best sellers."),
-    outputSchema: s.actionOutput({
-        marketplace: marketplaceSchema,
-        categoryId: s.nullableInteger("Amazon category node ID resolved by Keepa."),
-        lastUpdate: s.nullableInteger("Best-seller list update time in Keepa Time minutes."),
+        range: s.anyOf("Sales-rank averaging interval: 0, 30, 90 or 180 days.", [
+            s.literal(0, { description: "Current rank." }),
+            s.literal(30, { description: "30-day average rank." }),
+            s.literal(90, { description: "90-day average rank." }),
+            s.literal(180, { description: "180-day average rank." }),
+        ]),
+        month: s.integer("Historical month from 1 to 12; requires year.", {
+            minimum: 1,
+            maximum: 12,
+        }),
+        year: s.integer("Four-digit year for a historical month; requires month."),
+        variations: s.boolean("Return all variations instead of one representative."),
+        sublist: s.boolean("Use subcategory rank instead of primary rank."),
+        ...windowInputFields,
+    }, { optional: ["range", "month", "year", "variations", "sublist", "offset", "limit"] }),
+    outputSchema: s.requiredObject("Keepa best-seller results.", {
+        marketplace: standardMarketplaceSchema,
+        categoryId: s.nullable(s.integer("Amazon category node ID resolved by Keepa.")),
+        lastUpdate: s.nullable(s.integer("Best-seller list update time in Keepa Time minutes.")),
         asins: s.array("Ordered Amazon ASINs, starting with the product having the lowest sales rank.", s.string("One Amazon ASIN.")),
-        raw: s.looseObject("The complete Keepa bestSellersList object."),
+        ...windowOutputFields,
+        raw: s.looseObject("Keepa bestSellersList metadata without the full ASIN list."),
         meta: responseMetaSchema,
-    }, "Keepa best-seller results."),
+    }),
 });
 const findDealsAction = defineProviderAction(service, {
     name: "find_deals",
     operationType: "read",
     description: "Find recently changed Amazon products with Keepa deal filters and bounded pagination.",
     requiredScopes: [],
-    inputSchema: s.actionInput({
-        marketplace: marketplaceSchema,
+    inputSchema: s.object("Input for finding Keepa deals.", {
+        marketplace: standardMarketplaceSchema,
         priceType: s.stringEnum("Keepa price or rank type whose change defines the deal.", keepaDealPriceTypes),
         page: s.nonNegativeInteger("Zero-based deal result page; each page contains at most 150 deals."),
         dateRange: s.integer("Change interval: 0 for one day, 1 for one week, 2 for one month, or 3 for 90 days.", {
@@ -385,6 +424,7 @@ const findDealsAction = defineProviderAction(service, {
         deltaRange: dealRangeSchema,
         deltaPercentRange: dealRangeSchema,
         salesRankRange: dealRangeSchema,
+        deltaLastRange: dealRangeSchema,
         titleSearch: s.nonEmptyString("Case-insensitive title keywords that must all appear in the product title."),
         minimumRating: s.integer("Minimum product rating multiplied by 10.", {
             minimum: 0,
@@ -401,45 +441,252 @@ const findDealsAction = defineProviderAction(service, {
         isPrimeExclusive: s.boolean("Whether to include only Prime Exclusive products."),
         mustHaveAmazonOffer: s.boolean("Whether products must have an offer sold and fulfilled by Amazon."),
         mustNotHaveAmazonOffer: s.boolean("Whether products must not have an offer sold and fulfilled by Amazon."),
-    }, ["marketplace", "priceType"], "Input for finding Keepa deals."),
-    outputSchema: s.actionOutput({
-        marketplace: marketplaceSchema,
+        isHighest: s.boolean("Whether the selected value must be the highest since tracking began."),
+        singleVariation: s.boolean("Return one randomly chosen variation per matching family."),
+        isRisers: s.boolean("Include only products whose price rose in the selected interval."),
+        filterErotic: s.boolean("Exclude adult items when true."),
+        warehouseConditions: s.array("Amazon Warehouse condition codes.", s.integer("One condition code.")),
+        ...Object.fromEntries(keepaDealAttributeNames.map((name) => [
+            name,
+            s.stringArray(`Values for the official ${name} deal attribute filter.`, {
+                itemDescription: `One ${name} value.`,
+            }),
+        ])),
+    }, {
+        optional: [
+            "page",
+            "dateRange",
+            "includeCategories",
+            "excludeCategories",
+            "currentRange",
+            "deltaRange",
+            "deltaPercentRange",
+            "salesRankRange",
+            "deltaLastRange",
+            "titleSearch",
+            "minimumRating",
+            "sortBy",
+            "invertSort",
+            "isLowestEver",
+            "isLowest90Days",
+            "isLowestOffer",
+            "isBackInStock",
+            "isOutOfStock",
+            "hasReviews",
+            "isPrimeExclusive",
+            "mustHaveAmazonOffer",
+            "mustNotHaveAmazonOffer",
+            "isHighest",
+            "singleVariation",
+            "isRisers",
+            "filterErotic",
+            "warehouseConditions",
+            ...keepaDealAttributeNames,
+        ],
+    }),
+    outputSchema: s.requiredObject("Keepa deal search results.", {
+        marketplace: standardMarketplaceSchema,
         deals: s.array("Deal records returned by Keepa.", s.looseObject("One Keepa deal record.", {
-            asin: s.nullableString("Amazon ASIN."),
-            title: s.nullableString("Amazon product title."),
+            asin: nullableStringSchema("Amazon ASIN."),
+            title: nullableStringSchema("Amazon product title."),
         })),
         categoryIds: s.array("Root category IDs represented in the results.", s.integer("One root category ID.")),
         categoryNames: s.array("Root category names represented in the results.", s.string("One root category name.")),
         categoryCount: s.array("Deal counts aligned with categoryIds and categoryNames.", s.integer("Deal count for one root category.")),
         raw: s.looseObject("The complete Keepa deals response object."),
         meta: responseMetaSchema,
-    }, "Keepa deal search results."),
+    }),
 });
 const getSellerSnapshotAction = defineProviderAction(service, {
     name: "get_seller_snapshot",
     operationType: "read",
     description: "Retrieve compact Keepa marketplace seller profiles, ratings, category statistics, brands, and competitors.",
     requiredScopes: [],
-    inputSchema: s.actionInput({
-        marketplace: marketplaceSchema,
+    inputSchema: s.requiredObject("Input for retrieving Keepa seller snapshots.", {
+        marketplace: standardMarketplaceSchema,
         sellerIds: s.array("Amazon marketplace seller IDs.", s.nonEmptyString("One Amazon seller ID."), {
             minItems: 1,
             maxItems: 100,
         }),
-    }, ["marketplace", "sellerIds"], "Input for retrieving Keepa seller snapshots."),
-    outputSchema: s.actionOutput({
-        marketplace: marketplaceSchema,
+    }),
+    outputSchema: s.requiredObject("Keepa seller snapshot results.", {
+        marketplace: standardMarketplaceSchema,
         sellers: s.array("Seller profiles returned by Keepa.", s.looseObject("One normalized Keepa seller profile.", {
             sellerId: s.string("Amazon seller ID."),
-            sellerName: s.nullableString("Amazon seller display name."),
-            currentRating: s.nullableInteger("Current seller rating percentage."),
+            sellerName: nullableStringSchema("Amazon seller display name."),
+            currentRating: nullableIntegerSchema("Current seller rating percentage."),
             ratingCount: s.nullable(s.array("Rating counts for the last 30, 90, and 365 days and lifetime.", s.integer("One seller rating count."))),
-            hasFba: s.nullableBoolean("Whether Keepa has observed current FBA listings."),
-            shipsFromChina: s.nullableBoolean("Whether Keepa identifies the seller as shipping from China."),
+            hasFba: s.nullable(s.boolean("Whether Keepa has observed current FBA listings.")),
+            shipsFromChina: s.nullable(s.boolean("Whether Keepa identifies the seller as shipping from China.")),
             raw: s.looseObject("The complete Keepa seller object."),
         })),
         meta: responseMetaSchema,
-    }, "Keepa seller snapshot results."),
+    }),
+});
+const lightningStateSchema = s.stringEnum("Official Keepa lightning deal state.", [
+    "AVAILABLE",
+    "WAITLIST",
+    "SOLDOUT",
+    "WAITLISTFULL",
+    "EXPIRED",
+    "SUPPRESSED",
+]);
+const sellerFinderFiltersSchema = s.looseObject("Official Seller Finder selection fields; other official filters are preserved.", {
+    search: s.nonEmptyString("Text query for seller discovery."),
+    sellerName: s.nonEmptyString("Seller display name to match."),
+    businessName: s.nonEmptyString("Registered business name to match."),
+    addressCountry: s.stringArray("Seller business country codes.", {
+        itemDescription: "One country code.",
+    }),
+    currentRating_gte: s.integer("Minimum current seller rating percentage."),
+    currentRatingCount_gte: s.integer("Minimum current seller rating count."),
+    totalStorefrontAsins_gte: s.integer("Minimum observed storefront ASIN count."),
+    brands: s.stringArray("Brands sold by the merchant.", { itemDescription: "One brand." }),
+    rootCategories_include: s.array("Root category IDs to include.", s.integer("One root category ID.")),
+    competitorSellerIds: s.stringArray("Seller IDs whose listing competitors should be found.", {
+        itemDescription: "One seller ID.",
+    }),
+    page: s.nonNegativeInteger("Zero-based seller result page."),
+    perPage: s.anyOf("Seller IDs per page; zero means 100, otherwise from 50 to 10000.", [
+        s.literal(0, { description: "Use Keepa's 100-seller page shortcut." }),
+        s.integer("Seller IDs requested per page.", { minimum: 50, maximum: 10_000 }),
+    ]),
+    sort: s.array("Up to three seller sort rules.", s.tuple([
+        s.nonEmptyString("Official Seller Finder field name."),
+        s.stringEnum("Ascending or descending order.", ["asc", "desc"]),
+    ], { description: "One seller sort rule." }), { maxItems: 3 }),
+});
+const searchProductsAction = defineProviderAction(service, {
+    name: "search_products",
+    operationType: "read",
+    description: "Search Amazon products by keyword in Amazon result order, without fetching more details.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for Keepa keyword product search.", {
+        marketplace: standardMarketplaceSchema,
+        term: s.nonEmptyString("Amazon product search terms."),
+        asinsOnly: s.boolean("Return only ordered ASINs instead of product objects."),
+        statsDays: s.positiveInteger("Recent days for free product statistics."),
+        statsRange: statsRangeSchema,
+        updateHours: s.integer("Refresh threshold in hours; zero can cost extra tokens.", {
+            minimum: 0,
+        }),
+        includeHistory: s.boolean("Include available product price history."),
+        includeRating: s.boolean("Include existing rating and review history, possibly at extra cost."),
+    }, {
+        optional: ["asinsOnly", "statsDays", "statsRange", "updateHours", "includeHistory", "includeRating"],
+    }),
+    outputSchema: s.requiredObject("Ordered Keepa keyword search results.", {
+        marketplace: standardMarketplaceSchema,
+        asins: s.array("Ordered matching ASINs.", s.string("One ASIN.")),
+        products: s.array("Product objects when ASIN-only mode is disabled.", productSnapshotSchema),
+        meta: responseMetaSchema,
+    }),
+});
+const lookupCategoriesAction = defineProviderAction(service, {
+    name: "lookup_categories",
+    operationType: "read",
+    description: "Look up up to ten Amazon category IDs and optionally their parent tree; ID zero lists roots.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for Keepa category lookup.", {
+        marketplace: standardMarketplaceSchema,
+        categoryIds: s.array("Category IDs, or a sole zero to list roots.", s.nonNegativeInteger("One category ID."), {
+            minItems: 1,
+            maxItems: 10,
+        }),
+        includeParents: s.boolean("Include parent categories up to the root."),
+    }, { optional: ["includeParents"] }),
+    outputSchema: s.requiredObject("Keepa category lookup results.", {
+        marketplace: standardMarketplaceSchema,
+        categories: s.array("Matched categories.", categorySchema),
+        categoryParents: s.array("Parent categories when requested.", categorySchema),
+        meta: responseMetaSchema,
+    }),
+});
+const findSellersAction = defineProviderAction(service, {
+    name: "find_sellers",
+    operationType: "read",
+    description: "Find seller IDs by official Seller Finder criteria without fetching seller profiles.",
+    requiredScopes: [],
+    inputSchema: s.requiredObject("Input for Keepa Seller Finder.", {
+        marketplace: standardMarketplaceSchema,
+        filters: sellerFinderFiltersSchema,
+    }),
+    outputSchema: s.requiredObject("Keepa Seller Finder results.", {
+        marketplace: standardMarketplaceSchema,
+        sellerIds: s.array("Ordered seller IDs in this upstream result page.", s.string("One seller ID.")),
+        totalResults: s.nullable(s.integer("Total sellers matched across pages.")),
+        meta: responseMetaSchema,
+    }),
+});
+const getMostRatedSellersAction = defineProviderAction(service, {
+    name: "get_most_rated_sellers",
+    operationType: "read",
+    description: "Get seller IDs ordered by rating count, with a local result window; each window fetches and pays for the full upstream list.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for most rated sellers.", {
+        marketplace: standardMarketplaceSchema,
+        ...windowInputFields,
+    }, { optional: ["offset", "limit"] }),
+    outputSchema: s.requiredObject("Most rated sellers result window.", {
+        marketplace: standardMarketplaceSchema,
+        sellerIds: s.array("Seller IDs ordered by rating count.", s.string("One seller ID.")),
+        ...windowOutputFields,
+        meta: responseMetaSchema,
+    }),
+});
+const getSellerStorefrontAction = defineProviderAction(service, {
+    name: "get_seller_storefront",
+    operationType: "read",
+    description: "Inspect one seller's observed storefront ASINs and aligned last-seen times; the list can be incomplete.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for one seller storefront.", {
+        marketplace: standardMarketplaceSchema,
+        sellerId: s.nonEmptyString("One Amazon seller ID that does not contain commas.", { pattern: "^[^,]+$" }),
+        ...windowInputFields,
+    }, { optional: ["offset", "limit"] }),
+    outputSchema: s.requiredObject("Observed seller storefront window.", {
+        marketplace: standardMarketplaceSchema,
+        seller: s.nullable(s.looseObject("Seller profile without full storefront arrays.")),
+        items: s.array("Observed ASIN and last-seen pairs.", s.requiredObject("One storefront listing observation.", {
+            asin: s.string("Amazon ASIN."),
+            lastSeen: s.nullable(s.integer("Last observed Keepa Time minute.")),
+        })),
+        ...windowOutputFields,
+        meta: responseMetaSchema,
+    }),
+});
+const getLightningDealAction = defineProviderAction(service, {
+    name: "get_lightning_deal",
+    operationType: "read",
+    description: "Get lightning deals for a required ASIN, avoiding the costly full-list request.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for one product's lightning deal.", {
+        marketplace: standardMarketplaceSchema,
+        asin: asinSchema,
+        state: lightningStateSchema,
+    }, { optional: ["state"] }),
+    outputSchema: s.requiredObject("Lightning deals for one ASIN.", {
+        marketplace: standardMarketplaceSchema,
+        lightningDeals: s.array("Lightning deal objects.", s.looseObject("One upstream lightning deal.")),
+        meta: responseMetaSchema,
+    }),
+});
+const listLightningDealsAction = defineProviderAction(service, {
+    name: "list_lightning_deals",
+    operationType: "read",
+    description: "List lightning deals with a local result window; Keepa charges 500 tokens for each full upstream request, regardless of window size.",
+    requiredScopes: [],
+    inputSchema: s.object("Input for the full Keepa lightning deal list.", {
+        marketplace: standardMarketplaceSchema,
+        state: lightningStateSchema,
+        ...windowInputFields,
+    }, { optional: ["state", "offset", "limit"] }),
+    outputSchema: s.requiredObject("Lightning deal result window.", {
+        marketplace: standardMarketplaceSchema,
+        lightningDeals: s.array("Lightning deals in this local window.", s.looseObject("One upstream lightning deal.")),
+        ...windowOutputFields,
+        meta: responseMetaSchema,
+    }),
 });
 export const keepaActions = [
     getTokenStatusAction,
@@ -450,36 +697,11 @@ export const keepaActions = [
     getBestSellersAction,
     findDealsAction,
     getSellerSnapshotAction,
+    searchProductsAction,
+    lookupCategoriesAction,
+    findSellersAction,
+    getMostRatedSellersAction,
+    getSellerStorefrontAction,
+    getLightningDealAction,
+    listLightningDealsAction,
 ];
-function withProductRequestRules(schema) {
-    return {
-        ...schema,
-        allOf: [
-            {
-                if: {
-                    required: ["offers"],
-                },
-                then: {
-                    properties: {
-                        asins: {
-                            maxItems: 20,
-                        },
-                    },
-                },
-            },
-            {
-                if: {
-                    required: ["onlyLiveOffers"],
-                    properties: {
-                        onlyLiveOffers: {
-                            const: true,
-                        },
-                    },
-                },
-                then: {
-                    required: ["offers"],
-                },
-            },
-        ],
-    };
-}