@usagekit/providers 0.8.0 → 0.9.0

package/dist/priced-request.js

@@ -0,0 +1,234 @@
+const credentialQuery = /^(api[_-]?key|access[_-]?token|token|authorization|password|secret|(?:.*[_-])?credentials?)$/i;
+const credentialHeader = /^(authorization|proxy-authorization|cookie|set-cookie|(?:x-)?api[_-]?key|(?:x-)?access[_-]?token|(?:x-)?auth[_-]?token|(?:x-)?(?:.*[_-])?credentials?)$/i;
+export class RequestPricingError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** RFC 9110 media types are case-insensitive; structured JSON suffixes are JSON too. */
+export function isJsonMediaType(value) {
+    const type = value?.split(";")[0]?.trim().toLowerCase() ?? "";
+    return (type === "application/json" ||
+        /^[!#$%&'*+.^_`|~0-9a-z-]+\/[!#$%&'*+.^_`|~0-9a-z-]+\+json$/.test(type));
+}
+function freeze(value) {
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** 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 class PricedRequest {
+    method;
+    url;
+    headers;
+    parsed;
+    matched;
+    input;
+    admission;
+    estimate;
+    auth;
+    #bytes;
+    constructor(method, url, headers, parsed, matched, input, admission, estimate, bytes, auth) {
+        this.method = method;
+        this.url = url;
+        this.headers = headers;
+        this.parsed = parsed;
+        this.matched = matched;
+        this.input = input;
+        this.admission = admission;
+        this.estimate = estimate;
+        this.auth = auth;
+        this.#bytes = bytes;
+        Object.freeze(this);
+    }
+    get body() {
+        return this.#bytes?.slice();
+    }
+    static async price({ meter, catalog, input, request, expectedOperation, rejectUnknown, allowUnknownDispatch = false, }) {
+        const descriptor = catalog.providers().find((p) => p.id === input.provider);
+        if (!descriptor)
+            throw new RequestPricingError("invalid_provider_request");
+        let target;
+        let headers;
+        // Resolve and validate before catalog callbacks. Reject userinfo rather than retaining it.
+        try {
+            const base = new URL(descriptor.upstream);
+            target = new URL(request.url, base);
+            const prefix = base.pathname.replace(/\/$/, "");
+            if (base.username ||
+                base.password ||
+                target.username ||
+                target.password ||
+                target.protocol !== "https:" ||
+                target.origin !== base.origin ||
+                (prefix && target.pathname !== prefix && !target.pathname.startsWith(prefix + "/")))
+                throw new Error("InvalidUpstream");
+            const auth = descriptor.auth;
+            for (const key of [...target.searchParams.keys()]) {
+                if (credentialQuery.test(key) ||
+                    (auth.kind === "query" && key.toLowerCase() === auth.param.toLowerCase()))
+                    target.searchParams.delete(key);
+            }
+            const cleanHeaders = new Headers(request.headers);
+            for (const key of [...cleanHeaders.keys()]) {
+                if (credentialHeader.test(key) ||
+                    (auth.kind === "header" && key === auth.name.toLowerCase()) ||
+                    descriptor.stripRequestHeaders?.some((name) => key === name.toLowerCase()))
+                    cleanHeaders.delete(key);
+            }
+            headers = Object.fromEntries(cleanHeaders);
+        }
+        catch {
+            throw new RequestPricingError("invalid_provider_request");
+        }
+        const url = target.href;
+        const auth = freeze(structuredClone(descriptor.auth));
+        const pricesBody = descriptor.pricingInputs.includes("body");
+        let bytes;
+        let value;
+        let invalidJson = false;
+        if (request.body !== undefined) {
+            const raw = request.body instanceof Uint8Array || typeof request.body === "string";
+            try {
+                bytes =
+                    request.body instanceof Uint8Array
+                        ? Uint8Array.from(request.body)
+                        : new TextEncoder().encode(typeof request.body === "string" ? request.body : JSON.stringify(request.body));
+            }
+            catch {
+                throw new RequestPricingError("invalid_provider_request");
+            }
+            // Host JSON objects have an implicit JSON media type; raw bytes do not.
+            if (!raw && !headers["content-type"])
+                headers["content-type"] = "application/json";
+            value = new TextDecoder().decode(bytes);
+            if (pricesBody && isJsonMediaType(headers["content-type"])) {
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    invalidJson = true;
+                }
+            }
+        }
+        const parsed = {
+            method: request.method,
+            url,
+            headers,
+            ...(bytes === undefined ? {} : { body: value }),
+        };
+        let matched;
+        try {
+            matched = catalog.match(input.provider, parsed);
+        }
+        catch (error) {
+            throw new RequestPricingError(invalidJson ? "invalid_json" : "invalid_provider_request", error instanceof Error ? error.message : undefined);
+        }
+        if (matched.operation === "unknown") {
+            if (rejectUnknown)
+                throw new RequestPricingError("unknown_operation");
+        }
+        else if (pricesBody && matched.operation.billable && bytes !== undefined) {
+            if (invalidJson)
+                throw new RequestPricingError("invalid_json");
+            if (!isJsonMediaType(headers["content-type"]))
+                throw new RequestPricingError("invalid_provider_request");
+            bytes = new TextEncoder().encode(JSON.stringify(value));
+            headers["content-type"] = "application/json";
+        }
+        const uncertain = matched.operation !== "unknown" && !catalog.canEstimate(input.provider, matched.options);
+        if (expectedOperation !== undefined &&
+            (matched.operation === "unknown" || matched.operation.id !== expectedOperation))
+            throw new RequestPricingError("operation_mismatch");
+        // Isolate even references retained by a custom matcher before the first await.
+        const parsedSnapshot = freeze(structuredClone(parsed));
+        const headerSnapshot = freeze({ ...headers });
+        const snapshot = freeze(structuredClone(input));
+        const match = freeze(structuredClone(matched));
+        const { estimate: requestedEstimate, estimateSource, providerPriceVersion, ...restInput } = snapshot;
+        // Request uncertainty replaces every caller price and its provenance. The Meter owns
+        // funding, passthrough and budget admission, including requests-only unknown estimates.
+        const baseInput = uncertain
+            ? restInput
+            : {
+                ...restInput,
+                ...(estimateSource === undefined ? {} : { estimateSource }),
+                ...(providerPriceVersion === undefined ? {} : { providerPriceVersion }),
+            };
+        const boundedEstimate = requestedEstimate &&
+            input.fundingSource === "byok" &&
+            match.operation !== "unknown" &&
+            !uncertain
+            ? catalog.boundEstimate(input.provider, match.operation.id, match.options, requestedEstimate)
+            : requestedEstimate;
+        const admission = await meter.reserve({
+            ...baseInput,
+            operation: match.operation === "unknown" ? "unknown" : match.operation.id,
+            ...(uncertain
+                ? {
+                    estimate: [{ unit: "requests", value: 1n, scale: 0 }],
+                    estimateSource: "unknown",
+                }
+                : match.operation === "unknown"
+                    ? allowUnknownDispatch
+                        ? {
+                            estimate: [{ unit: "requests", value: 1n, scale: 0 }],
+                            estimateSource: "unknown",
+                        }
+                        : {}
+                    : {
+                        ...(boundedEstimate === undefined ? {} : { estimate: boundedEstimate }),
+                        options: match.options,
+                    }),
+        });
+        const estimate = admission.outcome === "reserved" ? admission.operation.estimate : [];
+        return new PricedRequest(parsedSnapshot.method, url, headerSnapshot, parsedSnapshot, match, snapshot, freeze(structuredClone(admission)), freeze(structuredClone(estimate)), bytes, auth);
+    }
+}
+/** 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 function applyProviderCredentials(auth, url, headers, credentials) {
+    try {
+        const { secret } = credentials;
+        if (auth.kind === "query") {
+            // URLSearchParams mutation re-encodes unrelated values, bare flags and invalid bytes.
+            const pair = new URLSearchParams([[auth.param, secret]]).toString();
+            url.search = url.search ? `${url.search}&${pair}` : `?${pair}`;
+        }
+        else if (auth.kind === "basic") {
+            const encoded = btoa(Array.from(new TextEncoder().encode(secret), (byte) => String.fromCharCode(byte)).join(""));
+            headers.set("Authorization", `Basic ${encoded}`);
+        }
+        else if (auth.kind === "bearer")
+            headers.set("Authorization", `Bearer ${secret}`);
+        else
+            headers.set(auth.name, `${auth.prefix ?? ""}${secret}`);
+    }
+    catch {
+        throw new Error("invalid_provider_credentials");
+    }
+}
+/** The only fetch boundary used by proxy and recorder. Pass null explicitly for no auth. */
+export async function dispatchPricedRequest(request, transport, signal, credentials) {
+    const url = new URL(request.url);
+    const headers = new Headers(request.headers);
+    if (credentials !== null)
+        applyProviderCredentials(request.auth, url, headers, credentials);
+    const body = request.body;
+    return transport(url.href, {
+        method: request.method,
+        headers,
+        redirect: "error",
+        signal,
+        ...(body === undefined ? {} : { body }),
+    });
+}

package/dist/prices.d.ts

@@ -7,5 +7,7 @@ import type { EstimateInput } from "./types.js";
  * win, then later validFrom. An operation priced per plan resolves nothing without a plan.
  */
 export declare function selectPriceRow(input: EstimateInput): PriceRow | undefined;
-/** Default estimate: one call at the selected row's per-unit price; empty without a row. */
+/** List formula or item override; an absent required item count leaves the price unknown. */
+export declare function calculatePrice(row: PriceRow, options: Readonly<Record<string, string>>, itemPrice?: Quantity): Quantity | undefined;
+/** Default estimate: selected base price and optional formula; empty without a row or count. */
 export declare function listEstimate(input: EstimateInput): Quantity[];

package/dist/prices.js

@@ -1,3 +1,4 @@
+import { addQuantity, formatQuantity } from "@usagekit/core";
 import { decimalQuantity } from "./receipts.js";
 /**
  * The price row behind a list estimate. Rows must name the operation, match the connection plan
@@ -18,8 +19,64 @@ export function selectPriceRow(input) {
         return bp - ap || bo - ao || b.validFrom.localeCompare(a.validFrom);
     })[0];
 }
-/** Default estimate: one call at the selected row's per-unit price; empty without a row. */
+/** Exact multiplication; reduce only trailing zeros, never round a coefficient. */
+function multiply(a, b) {
+    let value = a.value * b.value, scale = a.scale + b.scale;
+    while (scale > 18 && value % 10n === 0n) {
+        value /= 10n;
+        scale--;
+    }
+    if (scale > 18)
+        throw new Error("InvalidInput: calculation precision exceeds 18");
+    return decimalQuantity(formatQuantity({ value, scale, unit: a.unit }), a.unit);
+}
+const count = (value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d+$/.test(value))
+        throw new Error("InvalidInput: expected integer pricing count");
+    return BigInt(value);
+};
+/** List formula or item override; an absent required item count leaves the price unknown. */
+export function calculatePrice(row, options, itemPrice) {
+    const base = decimalQuantity(row.perUnit, row.unit), c = row.calculation;
+    if (!c) {
+        if (itemPrice)
+            throw new Error("InvalidInput: item price requires a base-plus-items row");
+        return base;
+    }
+    if (c.kind === "additional_pages") {
+        if (itemPrice)
+            throw new Error("InvalidInput: item price requires a base-plus-items row");
+        const depth = count(options[c.depthOption], BigInt(c.pageSize));
+        if (depth < 1n)
+            throw new Error("InvalidInput: depth must be positive");
+        const pages = (depth + BigInt(c.pageSize) - 1n) / BigInt(c.pageSize);
+        const extra = multiply(base, decimalQuantity(c.additionalPageFactor, row.unit));
+        return decimalQuantity(formatQuantity(addQuantity(base, { ...extra, value: extra.value * (pages - 1n) })), row.unit);
+    }
+    if (c.kind === "option_multiplier") {
+        if (itemPrice)
+            throw new Error("InvalidInput: item price requires a base-plus-items row");
+        return options[c.multiplierOption.key] === c.multiplierOption.value
+            ? multiply(base, decimalQuantity(c.multiplierOption.factor, row.unit))
+            : base;
+    }
+    if (itemPrice && itemPrice.unit !== row.unit)
+        throw new Error("InvalidInput: item price unit differs from row");
+    // An omitted count is unknown, not zero. Never reserve just the base for an item formula.
+    if (options[c.itemCountOption] === undefined)
+        return undefined;
+    const coefficient = itemPrice ?? decimalQuantity(c.perItem, row.unit);
+    const items = count(options[c.itemCountOption], 0n);
+    let total = addQuantity(base, { ...coefficient, value: coefficient.value * items });
+    if (c.multiplierOption && options[c.multiplierOption.key] === c.multiplierOption.value)
+        total = multiply(total, decimalQuantity(c.multiplierOption.factor, row.unit));
+    return decimalQuantity(formatQuantity(total), row.unit);
+}
+/** Default estimate: selected base price and optional formula; empty without a row or count. */
 export function listEstimate(input) {
     const row = selectPriceRow(input);
-    return row ? [decimalQuantity(row.perUnit, row.unit)] : [];
+    const quantity = row && calculatePrice(row, input.options);
+    return quantity ? [quantity] : [];
 }

package/dist/serpapi/descriptor.js

@@ -1,14 +1,14 @@
 export const pricing = "https://serpapi.com/pricing";
 const checked = "2026-09-25";
 const monthly = [
-    ["free", "Free (250 searches per month)", 250n],
-    ["starter", "Starter (25 USD, 1,000 searches per month)", 1000n],
-    ["developer", "Developer (75 USD, 5,000 searches per month)", 5000n],
-    ["production", "Production (150 USD, 15,000 searches per month)", 15000n],
-    ["bigdata", "Big Data (275 USD, 30,000 searches per month)", 30000n],
-    ["searcher", "Searcher (725 USD, 100,000 searches per month)", 100000n],
-    ["volume", "Volume (1,475 USD, 250,000 searches per month)", 250000n],
-    ["infrastructure", "Infrastructure (2,750 USD, 500,000 searches per month)", 500000n],
+    ["free", "Free (250 searches per month)", 250n, 0n],
+    ["starter", "Starter (25 USD, 1,000 searches per month)", 1000n, 2500n],
+    ["developer", "Developer (75 USD, 5,000 searches per month)", 5000n, 7500n],
+    ["production", "Production (150 USD, 15,000 searches per month)", 15000n, 15000n],
+    ["bigdata", "Big Data (275 USD, 30,000 searches per month)", 30000n, 27500n],
+    ["searcher", "Searcher (725 USD, 100,000 searches per month)", 100000n, 72500n],
+    ["volume", "Volume (1,475 USD, 250,000 searches per month)", 250000n, 147500n],
+    ["infrastructure", "Infrastructure (2,750 USD, 500,000 searches per month)", 500000n, 275000n],
 ];
 const row = (extra) => ({
     validFrom: checked,
@@ -28,15 +28,22 @@ export const descriptor = {
     id: "serpapi",
     label: "SerpApi",
     upstream: "https://serpapi.com",
+    pricingInputs: [],
     auth: { kind: "query", param: "api_key" },
     billing: { unit: "units", cycle: "monthly_plan" },
     plans: [
-        ...monthly.map(([id, label, searches]) => ({
+        ...monthly.map(([id, label, searches, feeCents]) => ({
             id,
             label,
             cycle: "monthly_plan",
             allowance: { unit: "units", value: searches },
             allowanceMode: "hard",
+            subscription: {
+                period: "month",
+                fee: { currency: "USD", units: feeCents * 10000n },
+                source: pricing,
+                checkedAt: checked,
+            },
         })),
         { id: "extra_credits", label: "Extra credits", cycle: "prepaid", allowanceMode: "hard" },
     ],

package/dist/testing/example.js

@@ -9,6 +9,7 @@ const source = "https://example.com/pricing";
 export const exampleDescriptor = {
     id: "example",
     label: "Example provider",
+    pricingInputs: ["query"],
     upstream: "https://api.example.com/v1",
     auth: { kind: "header", name: "X-Api-Key" },
     billing: { unit: "units", cycle: "monthly_plan" },

package/dist/types.d.ts

@@ -27,6 +27,10 @@ export type EstimateInput = {
 };
 /** The only code in a descriptor. Every function is pure and synchronous. */
 export type Extractors = {
+    /** False means request uncertainty cannot be overridden by a host or BYOK price. */
+    canEstimate?(options: Readonly<Record<string, string>>): boolean;
+    /** True when documented surcharges require the list upper bound even with an override. */
+    requiresListPriceFloor?(options: Readonly<Record<string, string>>): boolean;
     /** Estimate before the call from the matched operation, options and connection plan. Empty means no price. */
     estimate(input: EstimateInput): Quantity[];
     /** Options that select a price row, read from the request. Options are request data, never guessed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/providers",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Provider descriptors, catalog, price tables, extractors, fixtures and probes.",
@@ -31,7 +31,7 @@
     "prepack": "node ../../scripts/package-license.mjs"
   },
   "dependencies": {
-    "@usagekit/core": "0.8.0"
+    "@usagekit/core": "0.9.0"
   },
   "peerDependencies": {
     "vitest": ">=5.0.1 <6",