@usagekit/providers 0.8.0 → 0.9.1

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,27 @@ 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",
+            ...(name === "historical_rank_overview" ? ["dateFrom", "dateTo"] : []),
+        ])),
+        ...backlinks.map(([name, label]) => live(`backlinks.${name}.live`, label, `/v3/backlinks/${name}/live`, [
+            "itemCount",
+            ...(name === "history" ? ["dateFrom", "dateTo"] : []),
+        ])),
         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"),
     ],