@usagekit/providers 0.8.0 → 0.9.0

package/dist/dataforseo/request-pricing.js

@@ -0,0 +1,401 @@
+// Endpoint request tables fetched 2026-10-11. A new field is unknown until classified here.
+// Neutral fields select/filter/order results within the priced count; none adds a documented fee.
+// Price coefficients: https://dataforseo.com/pricing/serp/google-organic-serp-api
+// https://dataforseo.com/pricing/dataforseo-labs/dataforseo-google-api
+// https://dataforseo.com/pricing/backlinks/backlinks
+export const requestPricing = {
+    // Request field inventory: https://docs.dataforseo.com/v3/backlinks/backlinks/live/
+    "backlinks.backlinks.live": {
+        source: "https://docs.dataforseo.com/v3/backlinks/backlinks/live/",
+        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        priceFields: {
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+        },
+        neutralFields: [
+            "target",
+            "mode",
+            "custom_mode",
+            "filters",
+            "order_by",
+            "offset",
+            "search_after_token",
+            "backlinks_status_type",
+            "include_subdomains",
+            "exclude_internal_backlinks",
+            "rank_scale",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/backlinks/history/live/
+    "backlinks.history.live": {
+        source: "https://docs.dataforseo.com/v3/backlinks/history/live/",
+        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        priceFields: {
+            date_from: {
+                formula: "changes returned row count; count not derivable from the request",
+            },
+            date_to: {
+                formula: "changes returned row count; count not derivable from the request",
+            },
+        },
+        neutralFields: ["target", "rank_scale", "tag"],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/backlinks/summary/live/
+    "backlinks.summary.live": {
+        source: "https://docs.dataforseo.com/v3/backlinks/summary/live/",
+        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        priceFields: {},
+        neutralFields: [
+            "target",
+            "include_subdomains",
+            "include_indirect_links",
+            "exclude_internal_backlinks",
+            "internal_list_limit",
+            "backlinks_status_type",
+            "backlinks_filters",
+            "rank_scale",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_rank_overview/live/
+    "dataforseo_labs.google.domain_rank_overview.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_rank_overview/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+        },
+        neutralFields: [
+            "target",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "ignore_synonyms",
+            "offset",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_rank_overview/live/
+    "dataforseo_labs.google.historical_rank_overview.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_rank_overview/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            date_from: {
+                formula: "changes returned row count; count not derivable from the request",
+            },
+            date_to: {
+                formula: "changes returned row count; count not derivable from the request",
+            },
+        },
+        neutralFields: [
+            "target",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "correlate",
+            "ignore_synonyms",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live/
+    "dataforseo_labs.google.keyword_ideas.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 700,
+            },
+            offset_token: {
+                formula: "unknown: prior task options replace all supplied parameters except limit",
+                unpricedWhen: "present",
+            },
+        },
+        neutralFields: [
+            "keywords",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "closely_variants",
+            "ignore_synonyms",
+            "include_serp_info",
+            "offset",
+            "filters",
+            "order_by",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_overview/live/
+    "dataforseo_labs.google.keyword_overview.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_overview/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            keywords: {
+                formula: "base + 0.012 cents * keywords.length; clickstream doubles total",
+            },
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+        },
+        neutralFields: [
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "include_serp_info",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live/
+    "dataforseo_labs.google.keyword_suggestions.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_seed_keyword: {
+                formula: "false neutral; true unknown because extra item count is unconfirmed",
+                unpricedWhen: "true",
+            },
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+            offset_token: {
+                formula: "unknown: prior task options replace all supplied parameters except limit",
+                unpricedWhen: "present",
+            },
+        },
+        neutralFields: [
+            "keyword",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "include_serp_info",
+            "exact_match",
+            "ignore_synonyms",
+            "filters",
+            "order_by",
+            "offset",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live/
+    "dataforseo_labs.google.ranked_keywords.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+        },
+        neutralFields: [
+            "target",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "ignore_synonyms",
+            "item_types",
+            "offset",
+            "load_rank_absolute",
+            "historical_serp_mode",
+            "filters",
+            "order_by",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live/
+    "dataforseo_labs.google.related_keywords.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_seed_keyword: {
+                formula: "false neutral; true unknown because extra item count is unconfirmed",
+                unpricedWhen: "true",
+            },
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+        },
+        neutralFields: [
+            "keyword",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "depth",
+            "include_serp_info",
+            "ignore_synonyms",
+            "replace_with_core_keyword",
+            "filters",
+            "order_by",
+            "offset",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/relevant_pages/live/
+    "dataforseo_labs.google.relevant_pages.live": {
+        source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/relevant_pages/live/",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        priceFields: {
+            include_clickstream_data: {
+                formula: "true doubles entire request charge",
+            },
+            limit: {
+                formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
+                defaultCount: 100,
+            },
+        },
+        neutralFields: [
+            "target",
+            "location_name",
+            "location_code",
+            "language_name",
+            "language_code",
+            "item_types",
+            "offset",
+            "historical_serp_mode",
+            "ignore_synonyms",
+            "filters",
+            "order_by",
+            "tag",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/serp/google/organic/live/advanced/
+    "serp.google.organic.live.advanced": {
+        source: "https://docs.dataforseo.com/v3/serp/google/organic/live/advanced/",
+        formula: "pages * (base + rectangle surcharge + AI surcharge + 0.015 * clicks) * 5^operatorCount; full base per page; surcharge scaling is a conservative bound",
+        priceFields: {
+            keyword: {
+                formula: "5^n for distinct documented operators after decoding and NFKC; SERP only",
+            },
+            depth: {
+                formula: "ceil(depth / 10), default 10; take max with max_crawl_pages",
+            },
+            load_async_ai_overview: {
+                formula: "true adds one base per page before operator multiplication; high task priority uses the larger pricing-table amount",
+            },
+            max_crawl_pages: {
+                formula: "max(ceil(depth / 10), max_crawl_pages)",
+            },
+            search_param: {
+                formula: "5^n for distinct documented operators after decoding and NFKC; shared with keyword",
+            },
+            people_also_ask_click_depth: {
+                formula: "1..4 clicks at 0.015 cents per click; reserve on every page with operator multiplication",
+            },
+            calculate_rectangles: {
+                formula: "true adds one base per page before operator multiplication; high task priority uses the larger pricing-table amount",
+            },
+            url: {
+                formula: "unknown: provider derives other request fields from URL",
+                unpricedWhen: "present",
+            },
+        },
+        neutralFields: [
+            "location_code",
+            "language_code",
+            "device",
+            "location_name",
+            "language_name",
+            "os",
+            "tag",
+            "stop_crawl_on_match",
+            "remove_from_url",
+            "group_organic_results",
+            "browser_screen_width",
+            "browser_screen_height",
+            "browser_screen_resolution_ratio",
+            "location_coordinate",
+            "se_domain",
+            "target",
+            "target_search_mode",
+            "find_targets_in",
+            "ignore_targets_in",
+        ],
+    },
+    // Request field inventory: https://docs.dataforseo.com/v3/serp/google/organic/task_post/
+    "serp.google.organic.task_post": {
+        source: "https://docs.dataforseo.com/v3/serp/google/organic/task_post/",
+        formula: "pages * (base + rectangle surcharge + AI surcharge + 0.015 * clicks) * 5^operatorCount; full base per page; surcharge scaling is a conservative bound",
+        priceFields: {
+            keyword: {
+                formula: "5^n for distinct documented operators after decoding and NFKC; SERP only",
+            },
+            depth: {
+                formula: "ceil(depth / 10), default 10; take max with max_crawl_pages",
+            },
+            load_async_ai_overview: {
+                formula: "true adds one base per page before operator multiplication; high task priority uses the larger pricing-table amount",
+            },
+            priority: {
+                formula: "1 normal base 0.06 cents; 2 high base 0.12 cents",
+            },
+            max_crawl_pages: {
+                formula: "max(ceil(depth / 10), max_crawl_pages)",
+            },
+            search_param: {
+                formula: "5^n for distinct documented operators after decoding and NFKC; shared with keyword",
+            },
+            people_also_ask_click_depth: {
+                formula: "1..4 clicks at 0.015 cents per click; reserve on every page with operator multiplication",
+            },
+            calculate_rectangles: {
+                formula: "true adds one base per page before operator multiplication; high task priority uses the larger pricing-table amount",
+            },
+            url: {
+                formula: "unknown: provider derives other request fields from URL",
+                unpricedWhen: "present",
+            },
+        },
+        neutralFields: [
+            "location_code",
+            "language_code",
+            "device",
+            "pingback_url",
+            "postback_url",
+            "postback_data",
+            "location_name",
+            "location_coordinate",
+            "language_name",
+            "tag",
+            "os",
+            "stop_crawl_on_match",
+            "remove_from_url",
+            "expand_ai_overview",
+            "group_organic_results",
+            "browser_screen_width",
+            "browser_screen_height",
+            "browser_screen_resolution_ratio",
+            "target_search_mode",
+            "find_targets_in",
+            "ignore_targets_in",
+            "se_domain",
+        ],
+    },
+};

package/dist/execute.d.ts

@@ -1,6 +1,7 @@
-import type { DispatchGrant, Meter, MeterReserveInput, Operation, ReserveResult, SettleResult } from "@usagekit/core";
+import type { DispatchGrant, Meter, Operation, ReserveResult, SettleResult } from "@usagekit/core";
 import type { Catalog } from "./catalog.js";
-import type { ProviderRequest, ProviderResponse } from "./types.js";
+import type { PricedRequest } from "./priced-request.js";
+import type { ProviderResponse } from "./types.js";
 export type ProviderExecution = {
     outcome: "completed";
     response: ProviderResponse;
@@ -20,10 +21,9 @@ export type ProviderExecution = {
 export type ProviderExecutionInput = {
     meter: Meter;
     catalog: Catalog;
-    input: Omit<MeterReserveInput, "operation" | "options">;
-    request: ProviderRequest;
-    /** Reads the entire response before resolving. Inject credentials here, never in accounting. */
-    dispatch(request: ProviderRequest): Promise<{
+    request: PricedRequest;
+    /** Sends the priced bytes and reads the entire response. Add credentials only at transport. */
+    dispatch(request: PricedRequest): Promise<{
         response: ProviderResponse;
         body: unknown;
     }>;
@@ -32,5 +32,7 @@ export type ProviderExecutionInput = {
     leaseTtlMs?: number;
 };
 /** Execute one provider request. A replay, rejected reserve or lost grant never calls dispatch.
+ * Submits provider receipt evidence only. Hosts settle platform customer-charge measurements
+ * separately, using a unit distinct from the provider's units to retain the customer hold.
  * Long transports must finish within leaseTtlMs; streaming/recovery workers are host-owned. */
-export declare function executeProviderRequest({ meter, catalog, input, request, dispatch, now, holder, leaseTtlMs, }: ProviderExecutionInput): Promise<ProviderExecution>;
+export declare function executeProviderRequest({ meter, catalog, request, dispatch, now, holder, leaseTtlMs, }: ProviderExecutionInput): Promise<ProviderExecution>;

package/dist/execute.js

@@ -1,15 +1,9 @@
 /** Execute one provider request. A replay, rejected reserve or lost grant never calls dispatch.
+ * Submits provider receipt evidence only. Hosts settle platform customer-charge measurements
+ * separately, using a unit distinct from the provider's units to retain the customer hold.
  * Long transports must finish within leaseTtlMs; streaming/recovery workers are host-owned. */
-export async function executeProviderRequest({ meter, catalog, input, request, dispatch, now = () => new Date(), holder = "provider-wrapper", leaseTtlMs = 60000, }) {
-    const matched = catalog.match(input.provider, request);
-    const { estimate, ...base } = input;
-    const reserved = await meter.reserve({
-        ...base,
-        operation: matched.operation === "unknown" ? "unknown" : matched.operation.id,
-        ...(matched.operation === "unknown"
-            ? {}
-            : { ...(estimate === undefined ? {} : { estimate }), options: matched.options }),
-    });
+export async function executeProviderRequest({ meter, catalog, request, dispatch, now = () => new Date(), holder = "provider-wrapper", leaseTtlMs = 60000, }) {
+    const { matched, input, admission: reserved } = request;
     if (matched.operation === "unknown")
         return { outcome: "not_dispatched", result: reserved };
     const ref = {
@@ -50,7 +44,7 @@ export async function executeProviderRequest({ meter, catalog, input, request, d
     let returned, receipt;
     try {
         returned = await dispatch(request);
-        receipt = catalog.extract(input.provider, matched.operation.id, request, returned.response, returned.body);
+        receipt = catalog.extract(input.provider, matched.operation.id, request.parsed, returned.response, returned.body);
     }
     catch {
         const settled = await settle({

package/dist/index.d.ts

@@ -8,7 +8,6 @@ export type { Catalog, CatalogConnection, CatalogEstimate, CatalogMatch, Estimat
 export { proposePlanBudget } from "./budget.js";
 export type { BudgetTarget } from "./budget.js";
 export { listEstimate, selectPriceRow } from "./prices.js";
-export { matchOperation } from "./match.js";
 export { pointer } from "./pointer.js";
 export { decimalQuantity, numberText, moneyFromCents, moneyFromDollars, requestsMeasured, } from "./receipts.js";
 export { loadFixtures, missingFixtures, verifyFixture } from "./fixtures.js";
@@ -19,3 +18,5 @@ export { executeProviderRequest } from "./execute.js";
 export type { ProviderExecution, ProviderExecutionInput } from "./execute.js";
 export { parseBillingExport } from "./billing.js";
 export type { ParsedBillingExport } from "./billing.js";
+export { PricedRequest, RequestPricingError, dispatchPricedRequest, applyProviderCredentials, isJsonMediaType, } from "./priced-request.js";
+export type { RequestPricingInput, ProviderCredentials } from "./priced-request.js";

package/dist/index.js

@@ -1,7 +1,6 @@
 export { createCatalog, probeByPointers } from "./catalog.js";
 export { proposePlanBudget } from "./budget.js";
 export { listEstimate, selectPriceRow } from "./prices.js";
-export { matchOperation } from "./match.js";
 export { pointer } from "./pointer.js";
 export { decimalQuantity, numberText, moneyFromCents, moneyFromDollars, requestsMeasured, } from "./receipts.js";
 export { loadFixtures, missingFixtures, verifyFixture } from "./fixtures.js";
@@ -9,3 +8,4 @@ export { dataforseo } from "./dataforseo/index.js";
 export { serpapi } from "./serpapi/index.js";
 export { executeProviderRequest } from "./execute.js";
 export { parseBillingExport } from "./billing.js";
+export { PricedRequest, RequestPricingError, dispatchPricedRequest, applyProviderCredentials, isJsonMediaType, } from "./priced-request.js";

package/dist/priced-request.d.ts

@@ -0,0 +1,49 @@
+import type { Meter, MeterReserveInput, ProviderAuth, Quantity, ReserveResult } from "@usagekit/core";
+import type { Catalog, CatalogMatch } from "./catalog.js";
+import type { ProviderRequest } from "./types.js";
+export type RequestPricingInput = {
+    meter: Meter;
+    catalog: Catalog;
+    input: Omit<MeterReserveInput, "operation" | "options">;
+    /** Uint8Array is wire data; other bodies are host-supplied JSON values or text. */
+    request: ProviderRequest;
+    expectedOperation?: string;
+    rejectUnknown?: boolean;
+    /** Only non-strict proxy dispatch may reserve an unknown, unpriced request. */
+    allowUnknownDispatch?: boolean;
+};
+/** Trusted transport credentials are supplied separately and are never part of priced state. */
+export type ProviderCredentials = {
+    secret: string;
+};
+export declare class RequestPricingError extends Error {
+    readonly code: "invalid_json" | "invalid_provider_request" | "operation_mismatch" | "unknown_operation";
+    constructor(code: "invalid_json" | "invalid_provider_request" | "operation_mismatch" | "unknown_operation", message?: string);
+}
+/** RFC 9110 media types are case-insensitive; structured JSON suffixes are JSON too. */
+export declare function isJsonMediaType(value: string | null | undefined): boolean;
+/** Only pricing/admission can construct this snapshot. Bytes are copied on access, and all
+ * other state is deeply frozen. Neither caller mutations nor dispatch can change the price
+ * inputs. Credential fields are stripped before pricing; dispatch adds trusted authentication
+ * to a copy without retaining it in this snapshot. */
+export declare class PricedRequest {
+    #private;
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly parsed: ProviderRequest;
+    readonly matched: CatalogMatch;
+    readonly input: RequestPricingInput["input"];
+    readonly admission: ReserveResult;
+    readonly estimate: readonly Quantity[];
+    readonly auth: Readonly<ProviderAuth>;
+    private constructor();
+    get body(): Uint8Array<ArrayBuffer> | undefined;
+    static price({ meter, catalog, input, request, expectedOperation, rejectUnknown, allowUnknownDispatch, }: RequestPricingInput): Promise<PricedRequest>;
+}
+/** Apply trusted credentials to disposable transport objects. Hosts validate on throwaway
+ * objects before pricing; using this same helper at dispatch keeps both paths identical.
+ * Invalid credentials always throw a stable error without the credential value or cause. */
+export declare function applyProviderCredentials(auth: Readonly<ProviderAuth>, url: URL, headers: Headers, credentials: ProviderCredentials): void;
+/** The only fetch boundary used by proxy and recorder. Pass null explicitly for no auth. */
+export declare function dispatchPricedRequest(request: PricedRequest, transport: typeof fetch, signal: AbortSignal, credentials: ProviderCredentials | null): Promise<Response>;