@usagekit/providers 0.8.0 → 0.9.0

package/dist/catalog.d.ts

@@ -1,21 +1,10 @@
-import type { BalanceSnapshot, Budget, EstimateSource, OperationId, ProviderDescriptor, ProviderId, ProviderOperation, ProviderPlan, Quantity } from "@usagekit/core";
+import type { BalanceSnapshot, Budget, EstimateSource, ConnectionPolicy, OperationId, ProviderDescriptor, ProviderId, ProviderOperation, ProviderPlan, Quantity } from "@usagekit/core";
 import type { Extractors, ProviderModule, ProviderRequest, ProviderResponse, ReceiptDraft } from "./types.js";
 import type { BudgetTarget } from "./budget.js";
 export type { EstimateSource };
 /** Connection data the catalog needs; the catalog itself stays storage-free. */
-export type CatalogConnection = {
+export type CatalogConnection = Omit<ConnectionPolicy, "tracking"> & {
     id: string;
-    provider: ProviderId;
-    plan?: string;
-    /** Per-call manual price for (connection, operation). */
-    manualPrices?: Readonly<Record<OperationId, Quantity>>;
-    /** Median of this connection's settled receipts for the operation, with its sample size. */
-    measured?: (operation: OperationId) => {
-        quantity: Quantity;
-        samples: number;
-    } | undefined;
-    /** The plan allowance is exhausted: only overage rows apply. */
-    overage?: boolean;
 };
 export type CatalogEstimate = {
     /** Always includes one request for a billable operation; empty for a free operation. */
@@ -23,6 +12,8 @@ export type CatalogEstimate = {
     source: EstimateSource;
     /** "<provider>:<validFrom>" of the list row, when the source is list. */
     priceVersion?: string;
+    checkedAt?: string;
+    sampleSize?: number;
 };
 export type CatalogMatch = {
     operation: ProviderOperation;
@@ -45,7 +36,10 @@ export declare function createCatalog({ providers, enabled, measuredMinSamples,
 }): {
     providers: () => ProviderDescriptor[];
     match(providerId: ProviderId, request: ProviderRequest): CatalogMatch;
-    /** Resolution order: manual, measured with enough samples, list row, unknown. */
+    canEstimate(providerId: ProviderId, options: Readonly<Record<string, string>>): boolean;
+    /** BYOK caller estimates also retain any documented surcharge floor. */
+    boundEstimate(providerId: ProviderId, operationId: OperationId, options: Readonly<Record<string, string>>, quantities: readonly Quantity[]): Quantity[];
+    /** Resolution order: request safety, manual, measured with enough samples, list row, unknown. */
     estimate(connection: CatalogConnection, operationId: OperationId, options: Readonly<Record<string, string>>): CatalogEstimate;
     extract(providerId: ProviderId, operationId: OperationId | "unknown", request: ProviderRequest, response: ProviderResponse, body: unknown): ReceiptDraft;
     /** Price list and billing export parsers of an enabled descriptor, when it has them. */

package/dist/catalog.js

@@ -1,11 +1,23 @@
-import { validateDescriptor } from "@usagekit/core";
+import { compareQuantity, validateDescriptor } from "@usagekit/core";
 import { matchOperation } from "./match.js";
-import { selectPriceRow } from "./prices.js";
+import { calculatePrice, selectPriceRow } from "./prices.js";
 import { pointer } from "./pointer.js";
 import { decimalQuantity, requestsMeasured } from "./receipts.js";
 import { proposePlanBudget } from "./budget.js";
 const oneRequest = () => ({ value: 1n, scale: 0, unit: "requests" });
 const withRequest = (q) => q.some((x) => x.unit === "requests") ? q : [...q, oneRequest()];
+/** Compare exact quantities at their own scales; never round a reservation down. */
+function withFloor(quantities, floor) {
+    const result = [...quantities];
+    for (const bound of floor) {
+        const index = result.findIndex((q) => q.unit === bound.unit);
+        if (index < 0)
+            result.push(bound);
+        else if (compareQuantity(result[index], bound) < 0)
+            result[index] = bound;
+    }
+    return result;
+}
 function isoTimestamp(value) {
     if (typeof value !== "string" || !value)
         return undefined;
@@ -72,26 +84,60 @@ export function createCatalog({ providers, enabled, measuredMinSamples = 5, now
         providers: () => [...enabled].map((id) => modules.get(id).descriptor),
         match(providerId, request) {
             const module = active(providerId);
-            const operation = module && matchOperation(module.descriptor, request);
-            if (!module || !operation)
+            if (!module)
                 return { operation: "unknown" };
-            // Extractors always see an absolute URL, even for proxy paths.
-            const url = new URL(request.url, module.descriptor.upstream).href;
-            return { operation, options: module.extractors.options(operation, { ...request, url }) };
+            const url = new URL(request.url, module.descriptor.upstream);
+            if (module.descriptor.pricingInputs.includes("query")) {
+                const keys = new Set();
+                for (const key of url.searchParams.keys()) {
+                    if (keys.has(key))
+                        throw new Error("InvalidInput: duplicate query key");
+                    keys.add(key);
+                }
+            }
+            else
+                url.search = "";
+            // Pricing sees only declared inputs. Receipts and transport retain the full request.
+            const { body, ...rest } = request;
+            const pricingRequest = {
+                ...rest,
+                url: url.href,
+                ...(module.descriptor.pricingInputs.includes("body") && body !== undefined ? { body } : {}),
+            };
+            const operation = matchOperation(module.descriptor, pricingRequest);
+            if (!operation)
+                return { operation: "unknown" };
+            return { operation, options: module.extractors.options(operation, pricingRequest) };
+        },
+        canEstimate(providerId, options) {
+            return require(providerId).extractors.canEstimate?.(options) ?? true;
         },
-        /** Resolution order: manual, measured with enough samples, list row, unknown. */
+        /** BYOK caller estimates also retain any documented surcharge floor. */
+        boundEstimate(providerId, operationId, options, quantities) {
+            const module = require(providerId);
+            const operation = module.descriptor.operations.find((o) => o.id === operationId);
+            if (!operation || !module.extractors.requiresListPriceFloor?.(options))
+                return [...quantities];
+            const listed = module.extractors.estimate({
+                operation,
+                options,
+                prices: validPrices(module.descriptor),
+            });
+            return withFloor(quantities, listed);
+        },
+        /** Resolution order: request safety, manual, measured with enough samples, list row, unknown. */
         estimate(connection, operationId, options) {
             const module = active(connection.provider), operation = module?.descriptor.operations.find((o) => o.id === operationId);
             if (!module || !operation)
                 return { quantities: [oneRequest()], source: "unknown" };
             if (!operation.billable)
                 return { quantities: [], source: "list" };
-            const manual = connection.manualPrices?.[operationId];
-            if (manual)
-                return { quantities: withRequest([manual]), source: "manual" };
-            const measured = connection.measured?.(operationId);
-            if (measured && measured.samples >= measuredMinSamples)
-                return { quantities: withRequest([measured.quantity]), source: "measured" };
+            // Provider prices estimate BYOK upstream cost only. A host must supply customer prices
+            // explicitly for platform funding; neither manual nor list prices price credits.
+            if (connection.fundingSource !== "byok")
+                return { quantities: [oneRequest()], source: "unknown" };
+            if (module.extractors.canEstimate?.(options) === false)
+                return { quantities: [oneRequest()], source: "unknown" };
             const input = {
                 operation,
                 options,
@@ -99,14 +145,53 @@ export function createCatalog({ providers, enabled, measuredMinSamples = 5, now
                 ...(connection.plan !== undefined ? { plan: connection.plan } : {}),
                 ...(connection.overage ? { overage: true } : {}),
             };
-            const listed = module.extractors.estimate(input);
+            const listed = module.extractors.estimate(input), row = selectPriceRow(input);
+            const manual = connection.manualPrices?.[operationId];
+            const measured = manual ? undefined : connection.measured?.(operationId);
+            const override = manual ??
+                (measured &&
+                    Number.isSafeInteger(measured.samples) &&
+                    measured.samples >= measuredMinSamples
+                    ? measured.quantity
+                    : undefined);
+            if (override) {
+                const basis = manual ? connection.manualPriceBasis?.[operationId] : measured?.basis;
+                if (basis === "item" && (!row || row.calculation?.kind !== "base_plus_items"))
+                    return {
+                        quantities: withRequest(listed.filter((q) => q.unit !== override.unit)),
+                        source: "unknown",
+                    };
+                const quantity = basis === "item" ? calculatePrice(row, options, override) : override;
+                if (!quantity)
+                    return {
+                        quantities: withRequest(listed.filter((q) => q.unit !== override.unit)),
+                        source: "unknown",
+                    };
+                return {
+                    quantities: withRequest(withFloor([
+                        quantity,
+                        ...listed.filter((q) => q.unit !== quantity.unit && q.unit !== "requests"),
+                    ], module.extractors.requiresListPriceFloor?.(options) ? listed : [])),
+                    source: manual ? "manual" : "measured",
+                    ...(basis === "item" && row
+                        ? { priceVersion: `${module.descriptor.id}:${row.validFrom}`, checkedAt: row.checkedAt }
+                        : {}),
+                    ...(!manual && measured
+                        ? {
+                            sampleSize: measured.samples,
+                            ...(measured.checkedAt ? { checkedAt: measured.checkedAt } : {}),
+                        }
+                        : {}),
+                };
+            }
             if (!listed.length)
                 return { quantities: [oneRequest()], source: "unknown" };
-            const row = selectPriceRow(input);
             return {
                 quantities: withRequest(listed),
                 source: "list",
-                ...(row ? { priceVersion: `${module.descriptor.id}:${row.validFrom}` } : {}),
+                ...(row
+                    ? { priceVersion: `${module.descriptor.id}:${row.validFrom}`, checkedAt: row.checkedAt }
+                    : {}),
             };
         },
         extract(providerId, operationId, request, response, body) {

package/dist/dataforseo/descriptor.d.ts

@@ -4,7 +4,7 @@ export declare const labsPricing = "https://dataforseo.com/pricing/dataforseo-la
 export declare const backlinksPricing = "https://dataforseo.com/pricing/backlinks/backlinks";
 /**
  * Provider A: cost per call in every response, prepaid money balance, basic auth. List prices
- * are the per-task base price in cents; per-result charges, depth multipliers and paid
- * parameters come from the receipt.
+ * include request formulas in cents. Actual settlement continues to use response evidence.
+ * Formulas preserve host characterization values; the existing check date is not refreshed.
  */
 export declare const descriptor: ProviderDescriptor;

package/dist/dataforseo/descriptor.js

@@ -1,14 +1,17 @@
+import { requestPricing } from "./request-pricing.js";
 const docs = "https://docs.dataforseo.com/v3/";
 export const serpPricing = "https://dataforseo.com/pricing/serp/google-organic-serp-api";
 export const labsPricing = "https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api";
 export const backlinksPricing = "https://dataforseo.com/pricing/backlinks/backlinks";
 const checked = "2026-09-25";
-const live = (id, label, path) => ({
+const live = (id, label, path, optionKeys) => ({
     id,
     label,
     billable: true,
+    requestPricing: requestPricing[id],
     match: [{ method: "POST", path }],
     costEvidence: "response",
+    ...(optionKeys ? { optionKeys } : {}),
 });
 const free = (id, label, method, path) => ({
     id,
@@ -32,34 +35,64 @@ const backlinks = [
     ["history", "Backlinks history"],
     ["backlinks", "Backlinks live"],
 ];
-const row = (operation, perUnit, source, option) => ({
+const row = (operation, perUnit, source, option, calculation) => ({
     validFrom: checked,
     operation,
     ...(option ? { option } : {}),
     unit: "cents",
     perUnit,
+    ...(calculation ? { calculation } : {}),
     source,
     checkedAt: checked,
 });
+// Bill each SERP of up to 10 results at the full base: base * ceil(depth / 10).
+// https://docs.dataforseo.com/v3/serp/google/organic/live/advanced/
+// https://docs.dataforseo.com/v3/serp/google/organic/task_post/
+// The pricing page multiplies for each 10 results; the cost formula charges a full page 2.
+// https://dataforseo.com/pricing/serp/google-organic-serp-api
+// https://dataforseo.com/help-center/serp-api-cost-explained
+// The conflicting 25% later-page discount can only lower the charge, so do not apply it.
+// Unreturned results are refunded: full base per page is a conservative upper bound
+// that never under-reserves; omitted depth still means one page.
+// https://dataforseo.com/help-center/above-100-results-with-serp-api
+const pages = {
+    kind: "additional_pages",
+    depthOption: "depth",
+    pageSize: 10,
+    additionalPageFactor: "1",
+};
+const items = (perItem, clickstream = true) => ({
+    kind: "base_plus_items",
+    itemCountOption: "itemCount",
+    perItem,
+    ...(clickstream ? { multiplierOption: { key: "clickstream", value: "true", factor: "2" } } : {}),
+});
 /**
  * Provider A: cost per call in every response, prepaid money balance, basic auth. List prices
- * are the per-task base price in cents; per-result charges, depth multipliers and paid
- * parameters come from the receipt.
+ * include request formulas in cents. Actual settlement continues to use response evidence.
+ * Formulas preserve host characterization values; the existing check date is not refreshed.
  */
 export const descriptor = {
     id: "dataforseo",
     label: "DataForSEO",
     upstream: "https://api.dataforseo.com",
+    pricingInputs: ["body"],
     auth: { kind: "basic" },
     stripRequestHeaders: ["authorization"],
     billing: { unit: "cents", cycle: "prepaid" },
     plans: [{ id: "prepaid", label: "Prepaid balance", cycle: "prepaid", allowanceMode: "hard" }],
     prices: [
-        row("serp.google.organic.live.advanced", "0.2", serpPricing),
-        row("serp.google.organic.task_post", "0.06", serpPricing, { priority: "normal" }),
-        row("serp.google.organic.task_post", "0.12", serpPricing, { priority: "high" }),
-        ...labs.map(([name]) => row(`dataforseo_labs.google.${name}.live`, name === "historical_rank_overview" ? "12" : "1.2", labsPricing)),
-        ...backlinks.map(([name]) => row(`backlinks.${name}.live`, "2.4", backlinksPricing)),
+        row("serp.google.organic.live.advanced", "0.2", serpPricing, undefined, pages),
+        row("serp.google.organic.task_post", "0.06", serpPricing, { priority: "normal" }, pages),
+        row("serp.google.organic.task_post", "0.12", serpPricing, { priority: "high" }, pages),
+        ...labs.map(([name]) => row(`dataforseo_labs.google.${name}.live`, name === "historical_rank_overview" ? "12" : "1.2", labsPricing, undefined, 
+        // Per-request plus per-item, including ranked_keywords/domain_rank_overview.
+        // https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api
+        items(name === "historical_rank_overview" ? "0.12" : "0.012"))),
+        ...backlinks.map(([name]) => row(`backlinks.${name}.live`, "2.4", backlinksPricing, undefined, 
+        // Every returned row is billed, including summary and history.
+        // https://dataforseo.com/pricing/backlinks/backlinks
+        items("0.0036", false))),
     ],
     priceList: {
         kind: "endpoint",
@@ -68,19 +101,20 @@ export const descriptor = {
         mapping: "provider-specific",
     },
     operations: [
-        live("serp.google.organic.live.advanced", "Google organic SERP, live advanced", "/v3/serp/google/organic/live/advanced"),
+        live("serp.google.organic.live.advanced", "Google organic SERP, live advanced", "/v3/serp/google/organic/live/advanced", ["depth"]),
         {
             id: "serp.google.organic.task_post",
             label: "Google organic SERP, task post",
             billable: true,
             match: [{ method: "POST", path: "/v3/serp/google/organic/task_post" }],
-            optionKeys: ["priority"],
+            optionKeys: ["priority", "depth"],
             costEvidence: "deferred",
+            requestPricing: requestPricing["serp.google.organic.task_post"],
         },
         free("serp.google.organic.tasks_ready", "Google organic SERP, tasks ready", "GET", "/v3/serp/google/organic/tasks_ready"),
         free("serp.google.organic.task_get.advanced", "Google organic SERP, task get advanced", "GET", "/v3/serp/google/organic/task_get/advanced/:id"),
-        ...labs.map(([name, label]) => live(`dataforseo_labs.google.${name}.live`, label, `/v3/dataforseo_labs/google/${name}/live`)),
-        ...backlinks.map(([name, label]) => live(`backlinks.${name}.live`, label, `/v3/backlinks/${name}/live`)),
+        ...labs.map(([name, label]) => live(`dataforseo_labs.google.${name}.live`, label, `/v3/dataforseo_labs/google/${name}/live`, ["itemCount", "clickstream"])),
+        ...backlinks.map(([name, label]) => live(`backlinks.${name}.live`, label, `/v3/backlinks/${name}/live`, ["itemCount"])),
         free("appendix.user_data", "User data (balance, limits, prices)", "GET", "/v3/appendix/user_data"),
         free("dataforseo_labs.status", "Labs status", "GET", "/v3/dataforseo_labs/status"),
     ],

package/dist/dataforseo/extractors.js

@@ -1,7 +1,8 @@
-import { formatQuantity } from "@usagekit/core";
+import { addQuantity, formatQuantity } from "@usagekit/core";
+import { descriptor } from "./descriptor.js";
 import { listEstimate } from "../prices.js";
 import { pointer } from "../pointer.js";
-import { moneyFromDollars, requestsMeasured } from "../receipts.js";
+import { decimalQuantity, moneyFromDollars, requestsMeasured } from "../receipts.js";
 const tasksOf = (body) => {
     const tasks = pointer(body, "/tasks");
     return Array.isArray(tasks) ? tasks : [];
@@ -34,23 +35,287 @@ export const priceKeys = {
     ...Object.fromEntries(["summary", "history", "backlinks"].map((n) => [`backlinks.live.${n}`, `backlinks.${n}.live`])),
 };
 const withPriority = new Set(["serp.google.organic.task_post"]);
+const itemCountFields = {
+    "dataforseo_labs.google.keyword_overview.live": "keywords",
+    "dataforseo_labs.google.keyword_ideas.live": "limit",
+    "dataforseo_labs.google.keyword_suggestions.live": "limit",
+    "dataforseo_labs.google.related_keywords.live": "limit",
+    "dataforseo_labs.google.relevant_pages.live": "limit",
+    "backlinks.backlinks.live": "limit",
+    "dataforseo_labs.google.ranked_keywords.live": "limit",
+    "dataforseo_labs.google.domain_rank_overview.live": "limit",
+};
 function timestamp(text) {
     if (typeof text !== "string")
         return undefined;
     const m = /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) \+00:00$/.exec(text);
     return m ? new Date(`${m[1]}T${m[2]}Z`).toISOString() : undefined;
 }
+const nonNegativeInteger = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+/**
+ * The single task of a present billable body, with documented JSON types for every pricing
+ * field. Ambiguous body shapes (text, bare objects, empty or nested arrays) are InvalidInput.
+ * Unlisted keys, including alternate spellings, are separately marked unpriceable.
+ * Undefined fields count as omitted, as JSON serialization drops them. A request without a
+ * body carries no task and keeps the defaults.
+ */
+function billableTask(body) {
+    if (body === undefined)
+        return undefined;
+    if (Array.isArray(body) && body.length > 1)
+        throw new Error("InvalidInput: multiple DataForSEO tasks");
+    const task = Array.isArray(body) ? body[0] : undefined;
+    if (!task || typeof task !== "object" || Array.isArray(task))
+        throw new Error("InvalidInput: DataForSEO body must be an array with one task object");
+    const t = task;
+    for (const field of ["limit", "depth"])
+        if (t[field] !== undefined && !nonNegativeInteger(t[field]))
+            throw new Error(`InvalidInput: DataForSEO ${field}`);
+    if (t.priority !== undefined && t.priority !== 1 && t.priority !== 2)
+        throw new Error("InvalidInput: DataForSEO priority");
+    if (t.keywords !== undefined &&
+        (!Array.isArray(t.keywords) || t.keywords.some((keyword) => typeof keyword !== "string")))
+        throw new Error("InvalidInput: DataForSEO keywords");
+    for (const field of ["include_clickstream_data", "include_seed_keyword"])
+        if (t[field] !== undefined && typeof t[field] !== "boolean")
+            throw new Error(`InvalidInput: DataForSEO ${field}`);
+    return t;
+}
+const isSerp = (id) => id.startsWith("serp.google.organic.");
+function validateSerpDepth(depth) {
+    if (depth !== undefined &&
+        (!/^\d+$/.test(String(depth)) ||
+            BigInt(String(depth)) < 1n ||
+            BigInt(String(depth)) > BigInt(Number.MAX_SAFE_INTEGER)))
+        throw new Error("InvalidInput: DataForSEO SERP depth must be a positive safe integer");
+}
+// "Contains" is intentional, including embedded forms such as android: (id:).
+// Each distinct documented substring contributes a factor of five.
+// https://docs.dataforseo.com/v3/serp/google/organic/live/advanced/
+// https://docs.dataforseo.com/v3/serp/google/organic/task_post/
+// https://dataforseo.com/pricing/serp/google-organic-serp-api
+const searchOperators = [
+    "allinanchor:",
+    "allintext:",
+    "allintitle:",
+    "allinurl:",
+    "cache:",
+    "define:",
+    "definition:",
+    "filetype:",
+    "id:",
+    "inanchor:",
+    "info:",
+    "intext:",
+    "intitle:",
+    "inurl:",
+    "link:",
+    "site:",
+];
+function operatorCount(task) {
+    const values = [
+        ...(typeof task.keyword === "string" ? [task.keyword, decodeKeyword(task.keyword)] : []),
+        ...(typeof task.search_param === "string"
+            ? [task.search_param, decodeSearchParam(task.search_param)]
+            : []),
+    ];
+    const normalized = values
+        .flatMap((v) => [
+        v.normalize("NFKC").toLowerCase(),
+        v.normalize("NFKC").toUpperCase().toLowerCase(),
+        v
+            .normalize("NFKD")
+            .replace(/[\p{M}\p{Default_Ignorable_Code_Point}]/gu, "")
+            .toLowerCase(),
+    ])
+        .map((v) => v.replaceAll("-site:", ""));
+    // -site: is explicitly free. Other operator matches are conservative upper bounds.
+    // https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis
+    return searchOperators.filter((op) => normalized.some((value) => value.includes(op))).length;
+}
+/** Keywords are text, not query strings: preserve literal percent signs. Decode each
+ * valid escape run leniently; invalid UTF-8 bytes become replacement characters. */
+function decodeKeyword(value) {
+    value = value.normalize("NFKC");
+    for (let i = 0; i < 16; i++) {
+        const decoded = value
+            .replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+            try {
+                return decodeURIComponent(run);
+            }
+            catch {
+                return new TextDecoder().decode(Uint8Array.from(run.match(/[0-9a-f]{2}/gi), (hex) => parseInt(hex, 16)));
+            }
+        })
+            .normalize("NFKC");
+        if (decoded === value)
+            return decoded;
+        value = decoded;
+    }
+    throw new Error("InvalidInput: DataForSEO keyword encoding depth");
+}
+function validateSerpOptions(options) {
+    validateSerpDepth(options.depth);
+    for (const [field, max] of [
+        ["operatorCount", searchOperators.length],
+        ["clicks", 4],
+    ]) {
+        const value = options[field];
+        if (value !== undefined && (!/^\d+$/.test(value) || BigInt(value) > BigInt(max)))
+            throw new Error(`InvalidInput: DataForSEO SERP ${field}`);
+    }
+}
+function decodeSearchParam(value) {
+    value = value.normalize("NFKC");
+    // Decode nested query escapes before checking operators. Fail closed when malformed
+    // or still changing after the bound rather than passing an unchecked encoded operator.
+    for (let i = 0; i < 16; i++) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(value.replace(/\+/g, " ")).normalize("NFKC");
+        }
+        catch {
+            throw new Error("InvalidInput: DataForSEO malformed search_param escape");
+        }
+        if (decoded === value)
+            return decoded;
+        value = decoded;
+    }
+    throw new Error("InvalidInput: DataForSEO search_param encoding depth");
+}
+function validateSerpTask(task) {
+    validateSerpDepth(task.depth);
+    for (const field of ["calculate_rectangles", "load_async_ai_overview"])
+        if (task[field] !== undefined && typeof task[field] !== "boolean")
+            throw new Error(`InvalidInput: DataForSEO ${field}`);
+    for (const [field, max] of [
+        ["people_also_ask_click_depth", 4],
+        ["max_crawl_pages", 100],
+    ])
+        if (task[field] !== undefined &&
+            (!nonNegativeInteger(task[field]) || Number(task[field]) < 1 || Number(task[field]) > max))
+            throw new Error(`InvalidInput: DataForSEO ${field}`);
+    if (task.stop_crawl_on_match !== undefined && !Array.isArray(task.stop_crawl_on_match))
+        throw new Error("InvalidInput: DataForSEO stop_crawl_on_match");
+    for (const field of ["keyword", "search_param"])
+        if (task[field] !== undefined && typeof task[field] !== "string")
+            throw new Error(`InvalidInput: DataForSEO ${field}`);
+}
 export const extractors = {
-    estimate: listEstimate,
-    /** priority 1 is normal (the documented default when absent), 2 is high; anything else is unreadable. */
+    canEstimate: (options) => options.pricingUnknown !== "true",
+    // https://dataforseo.com/pricing/serp/google-organic-serp-api
+    // https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api
+    requiresListPriceFloor: (options) => Number(options.operatorCount ?? "0") > 0 ||
+        options.rectangles === "true" ||
+        options.asyncOverview === "true" ||
+        Number(options.clicks ?? "0") > 0 ||
+        options.crawlPages !== undefined ||
+        options.clickstream === "true",
+    estimate: (input) => {
+        if (isSerp(input.operation.id))
+            validateSerpOptions(input.options);
+        if (!extractors.canEstimate(input.options))
+            return [];
+        const estimates = listEstimate(input);
+        if (!isSerp(input.operation.id))
+            return estimates;
+        // Bound every page and operator combination, including add-ons. Field docs give
+        // $0.002 live / $0.0006 queued; the pricing table gives one base (higher for high priority).
+        // https://docs.dataforseo.com/v3/serp/google/organic/live/advanced/
+        // https://docs.dataforseo.com/v3/serp/google/organic/task_post/
+        // https://dataforseo.com/pricing/serp/google-organic-serp-api
+        // https://dataforseo.com/help-center/serp-api-cost-explained
+        const pages = (BigInt(input.options.depth ?? "10") + 9n) / 10n;
+        const operators = BigInt(input.options.operatorCount ?? "0");
+        const factor = 5n ** operators;
+        const addOns = Number(input.options.rectangles === "true") + Number(input.options.asyncOverview === "true");
+        const extra = decimalQuantity(input.operation.id.endsWith("task_post")
+            ? input.options.priority === "high"
+                ? "0.12"
+                : "0.06"
+            : "0.2", "cents");
+        const clicks = decimalQuantity("0.015", "cents");
+        return estimates.map((q) => {
+            if (q.unit !== "cents")
+                return q;
+            const total = addQuantity(addQuantity(q, { ...extra, value: extra.value * BigInt(addOns) * pages }), { ...clicks, value: clicks.value * BigInt(input.options.clicks ?? "0") * pages });
+            return decimalQuantity(formatQuantity({ ...total, value: total.value * factor }), "cents");
+        });
+    },
+    /** Request dimensions and documented defaults, separate from observed response quantities. */
     options: (operation, request) => {
-        if (!operation.optionKeys?.includes("priority"))
-            return {};
-        const first = Array.isArray(request.body) ? request.body[0] : null;
+        const first = operation.billable
+            ? billableTask(request.body)
+            : Array.isArray(request.body)
+                ? request.body[0]
+                : null;
         if (!first || typeof first !== "object")
             return {};
-        const priority = first.priority ?? 1;
-        return priority === 1 ? { priority: "normal" } : priority === 2 ? { priority: "high" } : {};
+        const task = first, options = {};
+        const keys = operation.optionKeys ?? [];
+        if (operation.billable) {
+            const fields = operation.requestPricing;
+            const unlisted = !fields ||
+                Object.keys(task).some((key) => task[key] !== undefined &&
+                    !Object.hasOwn(fields.priceFields, key) &&
+                    !fields.neutralFields.includes(key));
+            if (unlisted ||
+                task.limit === 0 ||
+                Number(task.limit) > 1000 ||
+                Object.entries(fields?.priceFields ?? {}).some(([field, rule]) => rule.unpricedWhen === "present"
+                    ? task[field] !== undefined
+                    : rule.unpricedWhen === "true" && task[field] === true))
+                options.pricingUnknown = "true";
+        }
+        if (operation.billable && isSerp(operation.id))
+            validateSerpTask(task);
+        if (keys.includes("priority")) {
+            const priority = task.priority ?? 1;
+            if (priority === 1)
+                options.priority = "normal";
+            else if (priority === 2)
+                options.priority = "high";
+        }
+        if (keys.includes("depth") && task.depth !== undefined)
+            options.depth = String(task.depth);
+        if (operation.billable && isSerp(operation.id)) {
+            if (task.max_crawl_pages !== undefined) {
+                options.crawlPages = String(task.max_crawl_pages);
+                options.depth = String(Math.max(Number(task.depth ?? 10), Number(task.max_crawl_pages) * 10));
+            }
+            const count = operatorCount(task);
+            if (count)
+                options.operatorCount = String(count);
+            if (task.calculate_rectangles === true)
+                options.rectangles = "true";
+            if (task.load_async_ai_overview === true)
+                options.asyncOverview = "true";
+            if (task.people_also_ask_click_depth !== undefined)
+                options.clicks = String(task.people_also_ask_click_depth);
+        }
+        if (keys.includes("itemCount")) {
+            const field = itemCountFields[operation.id];
+            const count = field === "keywords"
+                ? Array.isArray(task.keywords)
+                    ? task.keywords.length
+                    : undefined
+                : field === "limit"
+                    ? // Only omission uses the documented default; zero marks the request unknown.
+                        task.limit === undefined
+                            ? operation.requestPricing?.priceFields.limit?.defaultCount
+                            : task.limit
+                    : // Summary returns one row. History has no documented request count.
+                        // https://docs.dataforseo.com/v3/backlinks/summary/live/
+                        // https://docs.dataforseo.com/v3/backlinks/history/live/
+                        operation.id === "backlinks.summary.live"
+                            ? 1
+                            : undefined;
+            if (count !== undefined)
+                options.itemCount = String(count);
+        }
+        if (keys.includes("clickstream") && task.include_clickstream_data !== undefined)
+            options.clickstream = task.include_clickstream_data === false ? "false" : "true";
+        return options;
     },
     /**
      * Cost from the envelope `cost` (USD, every task of the call). A task status of 40000 or
@@ -115,12 +380,15 @@ export const extractors = {
                             continue;
                         if (!withPriority.has(operation) && level !== "normal")
                             continue;
+                        const calculation = descriptor.prices.find((r) => r.operation === operation && (!r.option || r.option.priority === level))?.calculation;
                         rows.push({
                             validFrom: checkedAt,
                             operation,
                             ...(withPriority.has(operation) ? { option: { priority: level } } : {}),
                             unit: "cents",
                             perUnit: formatQuantity(centsQuantity(entry.cost)),
+                            // The endpoint refreshes base prices; retain static formula metadata.
+                            ...(calculation ? { calculation } : {}),
                             source: priceListSource,
                             checkedAt,
                         });

package/dist/dataforseo/request-pricing.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderOperation } from "@usagekit/core";
+export declare const requestPricing: Readonly<Record<string, NonNullable<ProviderOperation["requestPricing"]>>>;