@usagekit/providers 0.4.0

package/dist/dataforseo/extractors.js

@@ -0,0 +1,145 @@
+import { formatQuantity } from "@usagekit/core";
+import { listEstimate } from "../prices.js";
+import { pointer } from "../pointer.js";
+import { moneyFromDollars, requestsMeasured } from "../receipts.js";
+const tasksOf = (body) => {
+    const tasks = pointer(body, "/tasks");
+    return Array.isArray(tasks) ? tasks : [];
+};
+const isCost = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
+const centsQuantity = (dollars) => ({
+    value: moneyFromDollars(dollars).units,
+    scale: 4,
+    unit: "cents",
+});
+const priceListSource = "https://docs.dataforseo.com/v3/appendix/user_data/";
+/**
+ * Price object keys `api.func_type.func_name` to operation ids. The key layout follows the
+ * documented field schema; a recorded user_data fixture confirms it. Unmapped keys, per-result
+ * entries and free functions are skipped.
+ */
+export const priceKeys = {
+    "serp.live.advanced": "serp.google.organic.live.advanced",
+    "serp.task_post.organic": "serp.google.organic.task_post",
+    ...Object.fromEntries([
+        "keyword_ideas",
+        "keyword_suggestions",
+        "related_keywords",
+        "keyword_overview",
+        "ranked_keywords",
+        "domain_rank_overview",
+        "historical_rank_overview",
+        "relevant_pages",
+    ].map((n) => [`dataforseo_labs.live.${n}`, `dataforseo_labs.google.${n}.live`])),
+    ...Object.fromEntries(["summary", "history", "backlinks"].map((n) => [`backlinks.live.${n}`, `backlinks.${n}.live`])),
+};
+const withPriority = new Set(["serp.google.organic.task_post"]);
+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;
+}
+export const extractors = {
+    estimate: listEstimate,
+    /** priority 1 is normal (the documented default when absent), 2 is high; anything else is unreadable. */
+    options: (operation, request) => {
+        if (!operation.optionKeys?.includes("priority"))
+            return {};
+        const first = 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" } : {};
+    },
+    /**
+     * Cost from the envelope `cost` (USD, every task of the call). A task status of 40000 or
+     * more, or an HTTP error, marks the receipt failed with whatever the provider charged.
+     * Deferred operations keep cost unknown and carry the task id for resolution.
+     */
+    extract: (operation, _request, response, body) => {
+        const tasks = tasksOf(body), id = extractors.requestId(body), cost = pointer(body, "/cost"), status = pointer(body, "/status_code");
+        const failed = response.status >= 400 ||
+            (typeof status === "number" && status >= 40000) ||
+            tasks.some((t) => typeof t.status_code === "number" && t.status_code >= 40000);
+        const known = operation.costEvidence !== "deferred" && isCost(cost);
+        const cents = known
+            ? { unit: "cents", quantity: centsQuantity(cost), certainty: "measured" }
+            : { unit: "cents", quantity: null, certainty: "unknown" };
+        return {
+            measurements: [cents, requestsMeasured()],
+            cost: known
+                ? { certainty: "measured", money: moneyFromDollars(cost) }
+                : { certainty: "unknown", money: null },
+            ...(id ? { providerRequestId: id } : {}),
+            cached: false,
+            failed,
+        };
+    },
+    requestId: (body) => {
+        const id = tasksOf(body)[0]?.id;
+        return typeof id === "string" && id ? id : undefined;
+    },
+    balance: (body) => {
+        const result = pointer(body, "/tasks/0/result/0");
+        const snapshot = { plan: "prepaid" };
+        const balance = pointer(result, "/money/balance"), total = pointer(result, "/money/total"), login = pointer(result, "/login"), perMinute = pointer(result, "/rates/limits/minute/total");
+        if (isCost(balance))
+            snapshot.remaining = centsQuantity(balance);
+        if (isCost(balance) && isCost(total) && total >= balance)
+            snapshot.used = {
+                ...centsQuantity(total),
+                value: centsQuantity(total).value - centsQuantity(balance).value,
+            };
+        if (typeof login === "string" && login)
+            snapshot.accountIdentity = login;
+        if (typeof perMinute === "number" && Number.isSafeInteger(perMinute))
+            snapshot.rateLimitPerHour = perMinute * 60;
+        return snapshot;
+    },
+    /** Maps price.api.func_type.func_name.priority to operation and priority option. */
+    priceList: (body, checkedAt) => {
+        const price = pointer(body, "/tasks/0/result/0/price");
+        const rows = [];
+        if (!price || typeof price !== "object")
+            return rows;
+        for (const [api, types] of Object.entries(price))
+            for (const [type, names] of Object.entries((types ?? {})))
+                for (const [name, priorities] of Object.entries((names ?? {}))) {
+                    const operation = priceKeys[`${api}.${type}.${name}`];
+                    if (!operation)
+                        continue;
+                    for (const [priority, entry] of Object.entries((priorities ?? {}))) {
+                        const level = priority.replace(/^priority_/, "");
+                        if (entry?.cost_type !== "per_request" || !isCost(entry.cost))
+                            continue;
+                        if (!withPriority.has(operation) && level !== "normal")
+                            continue;
+                        rows.push({
+                            validFrom: checkedAt,
+                            operation,
+                            ...(withPriority.has(operation) ? { option: { priority: level } } : {}),
+                            unit: "cents",
+                            perUnit: formatQuantity(centsQuantity(entry.cost)),
+                            source: priceListSource,
+                            checkedAt,
+                        });
+                    }
+                }
+        return rows;
+    },
+    /** Task history lines: the charge of each posted task, matched by task id. */
+    billingExport: (input) => tasksOf(input).flatMap((t) => {
+        const occurredAt = timestamp(pointer(t, "/result/0/datetime"));
+        if (typeof t.id !== "string" || !isCost(t.cost) || !occurredAt)
+            return [];
+        return [
+            {
+                providerRequestId: t.id,
+                operation: "serp.google.organic.task_post",
+                occurredAt,
+                cost: moneyFromDollars(t.cost),
+            },
+        ];
+    }),
+};

package/dist/dataforseo/index.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderModule } from "../types.js";
+/** Provider A: per-call cost, prepaid balance, basic auth. See docs/PROVIDERS.md section 5. */
+export declare const dataforseo: ProviderModule;
+export { priceKeys } from "./extractors.js";

package/dist/dataforseo/index.js

@@ -0,0 +1,5 @@
+import { descriptor } from "./descriptor.js";
+import { extractors } from "./extractors.js";
+/** Provider A: per-call cost, prepaid balance, basic auth. See docs/PROVIDERS.md section 5. */
+export const dataforseo = { descriptor, extractors };
+export { priceKeys } from "./extractors.js";

package/dist/eslint.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from "eslint";
+export declare const noDirectProviderCall: Rule.RuleModule;
+declare const plugin: {
+    rules: {
+        "no-direct-provider-call": Rule.RuleModule;
+    };
+};
+export default plugin;

package/dist/eslint.js

@@ -0,0 +1,70 @@
+/** A small glob dialect: * matches one path segment; ** matches any depth. */
+function matches(pattern, value) {
+    let source = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*" && pattern[i + 1] === "*") {
+            i++;
+            if (pattern[i + 1] === "/") {
+                source += "(?:.*/)?";
+                i++;
+            }
+            else
+                source += ".*";
+        }
+        else if (c === "*")
+            source += "[^/]*";
+        else
+            source += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`).test(value);
+}
+export const noDirectProviderCall = {
+    meta: {
+        type: "problem",
+        docs: { description: "Keep provider clients inside reviewed metering wrappers." },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    modules: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+                    wrappers: { type: "array", items: { type: "string", minLength: 1 } },
+                },
+                required: ["modules", "wrappers"],
+                additionalProperties: false,
+            },
+        ],
+        messages: { direct: "Import {{module}} only from an approved metering wrapper." },
+    },
+    create(context) {
+        const options = context.options[0];
+        if (!options)
+            return {};
+        const cwd = context.cwd.replace(/\\/g, "/").replace(/\/$/, "");
+        const filename = context.filename.replace(/\\/g, "/");
+        const relative = filename.startsWith(cwd + "/") ? filename.slice(cwd.length + 1) : filename;
+        if (options.wrappers.some((pattern) => matches(pattern, relative)))
+            return {};
+        const check = (node, value) => {
+            if (typeof value === "string" && options.modules.some((pattern) => matches(pattern, value)))
+                context.report({ node, messageId: "direct", data: { module: value } });
+        };
+        return {
+            ImportDeclaration: (node) => check(node, node.source.value),
+            ExportNamedDeclaration: (node) => check(node, node.source?.value),
+            ExportAllDeclaration: (node) => check(node, node.source.value),
+            ImportExpression: (node) => {
+                if (node.source.type === "Literal")
+                    check(node, node.source.value);
+            },
+            CallExpression: (node) => {
+                if (node.callee.type === "Identifier" &&
+                    node.callee.name === "require" &&
+                    node.arguments[0]?.type === "Literal")
+                    check(node, node.arguments[0].value);
+            },
+        };
+    },
+};
+const plugin = { rules: { "no-direct-provider-call": noDirectProviderCall } };
+export default plugin;

package/dist/execute.d.ts

@@ -0,0 +1,36 @@
+import type { DispatchGrant, Meter, MeterReserveInput, Operation, ReserveResult, SettleResult } from "@usagekit/core";
+import type { Catalog } from "./catalog.js";
+import type { ProviderRequest, ProviderResponse } from "./types.js";
+export type ProviderExecution = {
+    outcome: "completed";
+    response: ProviderResponse;
+    body: unknown;
+    operation: Operation | null;
+    accounting: "metered" | "passthrough";
+} | {
+    outcome: "not_dispatched";
+    result: ReserveResult | DispatchGrant;
+} | {
+    outcome: "transport_failed";
+    operation: Operation | null;
+} | {
+    outcome: "accounting_failed";
+    result: SettleResult;
+};
+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<{
+        response: ProviderResponse;
+        body: unknown;
+    }>;
+    now?: () => Date;
+    holder?: string;
+    leaseTtlMs?: number;
+};
+/** Execute one provider request. A replay, rejected reserve or lost grant never calls dispatch.
+ * 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>;

package/dist/execute.js

@@ -0,0 +1,81 @@
+/** Execute one provider request. A replay, rejected reserve or lost grant never calls dispatch.
+ * 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 }),
+    });
+    if (matched.operation === "unknown")
+        return { outcome: "not_dispatched", result: reserved };
+    const ref = {
+        namespace: input.scope.namespace,
+        principal: input.scope.principal,
+        operationId: input.operationId,
+    };
+    let grant;
+    if (reserved.outcome === "reserved" && !reserved.replayed) {
+        const intent = await meter.markDispatchIntent({
+            ...ref,
+            commandId: input.operationId + ":intent",
+            expectedVersion: reserved.operation.version,
+            holder,
+            leaseTtlMs,
+        });
+        if (!("granted" in intent) || !intent.granted)
+            return { outcome: "not_dispatched", result: intent };
+        grant = { version: intent.operation.version, leaseId: intent.lease.leaseId };
+    }
+    else if (reserved.outcome !== "passthrough" || reserved.replayed)
+        return { outcome: "not_dispatched", result: reserved };
+    const occurredAt = now().toISOString();
+    const settle = (receipt) => grant
+        ? meter.settle({
+            ...ref,
+            commandId: input.operationId + ":settle",
+            expectedVersion: grant.version,
+            authority: { kind: "lease", leaseId: grant.leaseId },
+            receipt: {
+                ...receipt,
+                id: input.operationId + ":receipt",
+                occurredAt,
+                recordedAt: now().toISOString(),
+            },
+        })
+        : undefined;
+    let returned, receipt;
+    try {
+        returned = await dispatch(request);
+        receipt = catalog.extract(input.provider, matched.operation.id, request, returned.response, returned.body);
+    }
+    catch {
+        const settled = await settle({
+            measurements: [
+                {
+                    unit: "requests",
+                    quantity: { unit: "requests", value: 1n, scale: 0 },
+                    certainty: "measured",
+                },
+            ],
+            cost: { certainty: "unknown", money: null },
+            cached: false,
+            failed: true,
+        });
+        if (settled && settled.outcome !== "settled")
+            return { outcome: "accounting_failed", result: settled };
+        return { outcome: "transport_failed", operation: settled?.operation ?? null };
+    }
+    const settled = await settle(receipt);
+    if (settled && settled.outcome !== "settled")
+        return { outcome: "accounting_failed", result: settled };
+    return {
+        outcome: "completed",
+        ...returned,
+        operation: settled?.operation ?? null,
+        accounting: grant ? "metered" : "passthrough",
+    };
+}

package/dist/fixtures.d.ts

@@ -0,0 +1,45 @@
+import type { BalanceSnapshot, BillingLine, PriceRow, ProviderDescriptor } from "@usagekit/core";
+import type { ProviderRequest, ProviderResponse, ReceiptDraft } from "./types.js";
+import type { Catalog } from "./catalog.js";
+/**
+ * One fixture file: a redacted request and response pair plus the expected parsed values.
+ * documentation fixtures are authored from public API documentation; recorded ones come from
+ * the local server recorder; synthetic ones exercise the catalog itself.
+ */
+export type Fixture = {
+    path: string;
+    origin: "documentation" | "recorded" | "synthetic";
+    provider: string;
+    operation: string;
+    source?: string;
+    description?: string;
+    recordedAt?: string;
+    request: ProviderRequest;
+    response: ProviderResponse & {
+        body: unknown;
+    };
+    expect: FixtureExpectation;
+};
+export type FixtureExpectation = {
+    options?: Record<string, string>;
+    receipt?: ReceiptDraft;
+    /** null asserts that the body carries no provider request id. */
+    requestId?: string | null;
+    balance?: BalanceSnapshot;
+    priceList?: {
+        checkedAt: string;
+        rows: PriceRow[];
+    };
+    billingLines?: BillingLine[];
+};
+/** Parsed fixture files keyed by path, for example the result of import.meta.glob(..., { eager: true }). */
+export type FixtureDirectory = Readonly<Record<string, unknown>>;
+/**
+ * Validate fixture files. Paths end in <operation>/<case>.json and the folder must name the
+ * fixture's operation. Quantities and money in expectations become bigint.
+ */
+export declare function loadFixtures(files: FixtureDirectory): Fixture[];
+/** Advertised operations without any fixture. A descriptor may not advertise them. */
+export declare function missingFixtures(descriptor: ProviderDescriptor, fixtures: readonly Fixture[]): string[];
+/** Problems of one fixture against the catalog: match, options and every declared expectation. */
+export declare function verifyFixture(catalog: Catalog, fixture: Fixture): string[];

package/dist/fixtures.js

@@ -0,0 +1,96 @@
+import { decodeMeterJson } from "@usagekit/core";
+const origins = ["documentation", "recorded", "synthetic"];
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * Validate fixture files. Paths end in <operation>/<case>.json and the folder must name the
+ * fixture's operation. Quantities and money in expectations become bigint.
+ */
+export function loadFixtures(files) {
+    return Object.entries(files)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, raw]) => {
+        const fail = (what) => new Error(`InvalidFixture: ${path}: ${what}`);
+        const segments = path.split("/");
+        if (segments.length < 2 || !path.endsWith(".json"))
+            throw fail("path");
+        if (!isObject(raw))
+            throw fail("object");
+        const data = decodeMeterJson(JSON.stringify(raw));
+        if (!origins.includes(String(data.origin)))
+            throw fail("origin");
+        if (typeof data.provider !== "string" || typeof data.operation !== "string")
+            throw fail("provider and operation");
+        if (segments.at(-2) !== data.operation)
+            throw fail("operation folder");
+        const request = data.request, response = data.response;
+        if (!isObject(request) ||
+            typeof request.method !== "string" ||
+            typeof request.url !== "string")
+            throw fail("request");
+        if (!isObject(response) || typeof response.status !== "number" || !("body" in response))
+            throw fail("response");
+        return {
+            ...data,
+            expect: (data.expect ?? {}),
+            path,
+        };
+    });
+}
+/** Advertised operations without any fixture. A descriptor may not advertise them. */
+export function missingFixtures(descriptor, fixtures) {
+    return descriptor.operations
+        .map((o) => o.id)
+        .filter((id) => !fixtures.some((f) => f.provider === descriptor.id && f.operation === id));
+}
+/** Key-order-insensitive deep equality with exact bigints. */
+function canonical(value) {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "undefined";
+}
+const same = (a, b) => canonical(a) === canonical(b);
+/** Problems of one fixture against the catalog: match, options and every declared expectation. */
+export function verifyFixture(catalog, fixture) {
+    const problems = [], e = fixture.expect, matched = catalog.match(fixture.provider, fixture.request);
+    const id = matched.operation === "unknown" ? "unknown" : matched.operation.id;
+    if (id !== fixture.operation)
+        return [`matched ${id}, expected ${fixture.operation}`];
+    const module = catalog.providers().find((d) => d.id === fixture.provider);
+    if (e.options && "options" in matched && !same(matched.options, e.options))
+        problems.push("options differ");
+    const declared = ["options", "receipt", "requestId", "balance", "priceList", "billingLines"].filter((k) => k in e);
+    if (!declared.length)
+        problems.push("fixture declares no expectation");
+    if (e.receipt) {
+        const receipt = catalog.extract(fixture.provider, fixture.operation, fixture.request, fixture.response, fixture.response.body);
+        if (!same(receipt, e.receipt))
+            problems.push("receipt differs");
+    }
+    if ("requestId" in e &&
+        catalog.requestId(fixture.provider, fixture.response.body) !== (e.requestId ?? undefined))
+        problems.push("request id differs");
+    if (e.balance && !same(catalog.probe(fixture.provider, fixture.response.body), e.balance))
+        problems.push("balance differs");
+    const parsers = catalog.parsers(module.id);
+    if (e.priceList) {
+        if (!parsers.priceList)
+            problems.push("no price list parser");
+        else if (!same(parsers.priceList(fixture.response.body, e.priceList.checkedAt), e.priceList.rows))
+            problems.push("price list differs");
+    }
+    if (e.billingLines) {
+        if (!parsers.billingExport)
+            problems.push("no billing export parser");
+        else if (!same(parsers.billingExport(fixture.response.body), e.billingLines))
+            problems.push("billing lines differ");
+    }
+    return problems;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Provider catalog: descriptors, match, estimate, extract, probe and plan budgets. Web runtime,
+ * no storage: connection data comes from the host. See docs/PROVIDERS.md.
+ */
+export type { Extractors, EstimateInput, ProviderModule, ProviderRequest, ProviderResponse, ReceiptDraft, } from "./types.js";
+export { createCatalog, probeByPointers } from "./catalog.js";
+export type { Catalog, CatalogConnection, CatalogEstimate, CatalogMatch, EstimateSource, } from "./catalog.js";
+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";
+export type { Fixture, FixtureDirectory, FixtureExpectation } from "./fixtures.js";
+export { dataforseo } from "./dataforseo/index.js";
+export { serpapi } from "./serpapi/index.js";
+export { executeProviderRequest } from "./execute.js";
+export type { ProviderExecution, ProviderExecutionInput } from "./execute.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+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";
+export { dataforseo } from "./dataforseo/index.js";
+export { serpapi } from "./serpapi/index.js";
+export { executeProviderRequest } from "./execute.js";

package/dist/match.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderDescriptor, ProviderOperation } from "@usagekit/core";
+import type { ProviderRequest } from "./types.js";
+/**
+ * The operation for a request: the longest literal path wins, then most query constraints, then
+ * an exact method over ANY. The request must target the upstream origin and base path.
+ */
+export declare function matchOperation(descriptor: ProviderDescriptor, request: ProviderRequest): ProviderOperation | undefined;

package/dist/match.js

@@ -0,0 +1,55 @@
+function pathScore(pattern, path) {
+    const want = pattern.split("/").filter(Boolean), have = path.split("/").filter(Boolean);
+    let literal = 0;
+    for (let i = 0; i < want.length; i++) {
+        const segment = want[i];
+        if (segment === "*" && i === want.length - 1)
+            return literal;
+        if (i >= have.length)
+            return null;
+        if (segment.startsWith(":"))
+            continue;
+        if (segment !== have[i])
+            return null;
+        literal += segment.length + 1;
+    }
+    return want.length === have.length ? literal : null;
+}
+function score(m, method, path, query) {
+    if (m.method !== "ANY" && m.method !== method)
+        return null;
+    const literal = pathScore(m.path, path);
+    if (literal === null)
+        return null;
+    const constraints = Object.entries(m.query ?? {});
+    for (const [key, expected] of constraints) {
+        const actual = query.get(key);
+        if (actual === null)
+            return null;
+        if (typeof expected === "string" ? actual !== expected : !expected.test(actual))
+            return null;
+    }
+    return [literal, constraints.length, m.method === "ANY" ? 0 : 1];
+}
+const better = (a, b) => a[0] !== b[0] ? a[0] > b[0] : a[1] !== b[1] ? a[1] > b[1] : a[2] > b[2];
+/**
+ * The operation for a request: the longest literal path wins, then most query constraints, then
+ * an exact method over ANY. The request must target the upstream origin and base path.
+ */
+export function matchOperation(descriptor, request) {
+    const upstream = new URL(descriptor.upstream), url = new URL(request.url, upstream);
+    if (url.origin !== upstream.origin)
+        return undefined;
+    const base = upstream.pathname.replace(/\/$/, "");
+    if (base && url.pathname !== base && !url.pathname.startsWith(base + "/"))
+        return undefined;
+    const path = url.pathname.slice(base.length) || "/", method = request.method.toUpperCase();
+    let best;
+    for (const op of descriptor.operations)
+        for (const m of op.match) {
+            const s = score(m, method, path, url.searchParams);
+            if (s && (!best || better(s, best.score)))
+                best = { op, score: s };
+        }
+    return best?.op;
+}

package/dist/pointer.d.ts

@@ -0,0 +1,2 @@
+/** RFC 6901 JSON pointer lookup; undefined when any step is missing. */
+export declare function pointer(value: unknown, path: string): unknown;

package/dist/pointer.js

@@ -0,0 +1,13 @@
+/** RFC 6901 JSON pointer lookup; undefined when any step is missing. */
+export function pointer(value, path) {
+    if (path === "")
+        return value;
+    let current = value;
+    for (const raw of path.replace(/^\//, "").split("/")) {
+        const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (current === null || typeof current !== "object" || !Object.hasOwn(current, key))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}

package/dist/prices.d.ts

@@ -0,0 +1,11 @@
+import type { PriceRow, Quantity } from "@usagekit/core";
+import type { EstimateInput } from "./types.js";
+/**
+ * The price row behind a list estimate. Rows must name the operation, match the connection plan
+ * (rows without plan apply to any plan) and the overage state, and every option they name must
+ * equal the request option. Plan-specific rows beat any-plan rows, then rows naming more options
+ * 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. */
+export declare function listEstimate(input: EstimateInput): Quantity[];

package/dist/prices.js

@@ -0,0 +1,25 @@
+import { decimalQuantity } from "./receipts.js";
+/**
+ * The price row behind a list estimate. Rows must name the operation, match the connection plan
+ * (rows without plan apply to any plan) and the overage state, and every option they name must
+ * equal the request option. Plan-specific rows beat any-plan rows, then rows naming more options
+ * win, then later validFrom. An operation priced per plan resolves nothing without a plan.
+ */
+export function selectPriceRow(input) {
+    const rows = input.prices.filter((r) => r.operation === input.operation.id);
+    if (input.plan === undefined && rows.some((r) => r.plan !== undefined))
+        return undefined;
+    const candidates = rows.filter((r) => (r.plan === undefined || r.plan === input.plan) &&
+        Boolean(r.overage) === Boolean(input.overage) &&
+        Object.entries(r.option ?? {}).every(([k, v]) => input.options[k] === v));
+    const rank = (r) => [r.plan ? 1 : 0, Object.keys(r.option ?? {}).length];
+    return candidates.sort((a, b) => {
+        const [ap, ao] = rank(a), [bp, bo] = rank(b);
+        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. */
+export function listEstimate(input) {
+    const row = selectPriceRow(input);
+    return row ? [decimalQuantity(row.perUnit, row.unit)] : [];
+}