@usagekit/providers 0.4.0

package/dist/receipts.d.ts

@@ -0,0 +1,10 @@
+import type { Measurement, Money, Quantity } from "@usagekit/core";
+/** Exact quantity of a nonnegative decimal string in a unit: "0.0150" cents is 150 at scale 4. */
+export declare function decimalQuantity(text: string, unit: string): Quantity;
+/** Exact decimal text of a JSON number, rounded to at most `digits` fractional digits. */
+export declare function numberText(n: number, digits: number): string;
+/** Money from a cents decimal string with up to four fractional digits. */
+export declare function moneyFromCents(cents: string): Money;
+/** Money from a USD amount reported as a JSON number; 1 USD is 1_000_000 money units. */
+export declare function moneyFromDollars(dollars: number): Money;
+export declare const requestsMeasured: (count?: bigint) => Measurement;

package/dist/receipts.js

@@ -0,0 +1,32 @@
+const decimalPattern = /^(\d+)(?:\.(\d+))?$/;
+/** Exact quantity of a nonnegative decimal string in a unit: "0.0150" cents is 150 at scale 4. */
+export function decimalQuantity(text, unit) {
+    const m = decimalPattern.exec(text);
+    if (!m || (m[2]?.length ?? 0) > 18)
+        throw new Error(`InvalidDecimal: ${text}`);
+    return { value: BigInt(m[1] + (m[2] ?? "")), scale: m[2]?.length ?? 0, unit };
+}
+/** Exact decimal text of a JSON number, rounded to at most `digits` fractional digits. */
+export function numberText(n, digits) {
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`InvalidDecimal: ${n}`);
+    const fixed = n.toFixed(digits);
+    return fixed.includes(".") ? fixed.replace(/0+$/, "").replace(/\.$/, "") : fixed;
+}
+/** Money from a cents decimal string with up to four fractional digits. */
+export function moneyFromCents(cents) {
+    const q = decimalQuantity(cents, "cents");
+    if (q.scale > 4)
+        throw new Error(`InvalidDecimal: ${cents}`);
+    return { units: q.value * 10n ** BigInt(4 - q.scale), currency: "USD" };
+}
+/** Money from a USD amount reported as a JSON number; 1 USD is 1_000_000 money units. */
+export function moneyFromDollars(dollars) {
+    const q = decimalQuantity(numberText(dollars, 6), "usd");
+    return { units: q.value * 10n ** BigInt(6 - q.scale), currency: "USD" };
+}
+export const requestsMeasured = (count = 1n) => ({
+    unit: "requests",
+    quantity: { value: count, scale: 0, unit: "requests" },
+    certainty: "measured",
+});

package/dist/serpapi/descriptor.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderDescriptor } from "@usagekit/core";
+export declare const pricing = "https://serpapi.com/pricing";
+/**
+ * Provider B: no per-call cost, monthly plans with a search allowance, query-parameter auth.
+ * A search costs one plan unit; past the allowance it draws one extra credit. Cloud and
+ * enterprise tiers are left to manual prices on the connection.
+ */
+export declare const descriptor: ProviderDescriptor;

package/dist/serpapi/descriptor.js

@@ -0,0 +1,97 @@
+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],
+];
+const row = (extra) => ({
+    validFrom: checked,
+    operation: "search",
+    unit: "units",
+    perUnit: "1",
+    source: pricing,
+    checkedAt: checked,
+    ...extra,
+});
+/**
+ * Provider B: no per-call cost, monthly plans with a search allowance, query-parameter auth.
+ * A search costs one plan unit; past the allowance it draws one extra credit. Cloud and
+ * enterprise tiers are left to manual prices on the connection.
+ */
+export const descriptor = {
+    id: "serpapi",
+    label: "SerpApi",
+    upstream: "https://serpapi.com",
+    auth: { kind: "query", param: "api_key" },
+    billing: { unit: "units", cycle: "monthly_plan" },
+    plans: [
+        ...monthly.map(([id, label, searches]) => ({
+            id,
+            label,
+            cycle: "monthly_plan",
+            allowance: { unit: "units", value: searches },
+            allowanceMode: "hard",
+        })),
+        { id: "extra_credits", label: "Extra credits", cycle: "prepaid", allowanceMode: "hard" },
+    ],
+    prices: [
+        ...monthly.map(([plan]) => row({ plan })),
+        row({ plan: "extra_credits" }),
+        row({ overage: true }),
+    ],
+    priceList: { kind: "static" },
+    operations: [
+        {
+            id: "search",
+            label: "Search",
+            billable: true,
+            match: [
+                { method: "GET", path: "/search" },
+                { method: "GET", path: "/search.json" },
+            ],
+            costEvidence: "none",
+            cacheable: {
+                keyParams: ["engine", "q", "location", "hl", "gl", "device"],
+                defaultTtlMs: 3600000,
+            },
+        },
+        {
+            id: "account",
+            label: "Account",
+            billable: false,
+            match: [
+                { method: "GET", path: "/account" },
+                { method: "GET", path: "/account.json" },
+            ],
+            costEvidence: "none",
+        },
+        {
+            id: "locations",
+            label: "Locations",
+            billable: false,
+            match: [{ method: "GET", path: "/locations.json" }],
+            costEvidence: "none",
+        },
+    ],
+    balance: {
+        operation: "account",
+        fields: {
+            remaining: "/plan_searches_left",
+            remainingUnit: "units",
+            allowance: "/searches_per_month",
+            used: "/this_month_usage",
+            resetsAt: "/plan_renewal_date",
+            plan: "/plan_id",
+            accountIdentity: "/account_email",
+            rateLimitPerHour: "/account_rate_limit_per_hour",
+        },
+    },
+    billingExport: { kind: "none", granularity: "per-day", matchKey: "window" },
+    docs: { pricing, api: "https://serpapi.com/search-api" },
+};

package/dist/serpapi/extractors.d.ts

@@ -0,0 +1,2 @@
+import type { Extractors } from "../types.js";
+export declare const extractors: Extractors;

package/dist/serpapi/extractors.js

@@ -0,0 +1,46 @@
+import { listEstimate } from "../prices.js";
+import { pointer } from "../pointer.js";
+import { requestsMeasured } from "../receipts.js";
+const zero = { units: 0n, currency: "USD" };
+const units = (value) => ({ value, scale: 0, unit: "units" });
+export const extractors = {
+    estimate: listEstimate,
+    options: () => ({}),
+    /**
+     * The provider reports no cost per call. A search settles as one estimated plan unit with zero
+     * marginal money (the plan fee is not a per-call charge); reconciliation compares
+     * this_month_usage deltas. Errored searches consume no search. Free endpoints cost nothing.
+     */
+    extract: (operation, _request, response, body) => {
+        const id = extractors.requestId(body);
+        const failed = response.status >= 400 || typeof pointer(body, "/error") === "string";
+        const common = { ...(id ? { providerRequestId: id } : {}), cached: false, failed };
+        if (!operation.billable)
+            return {
+                measurements: [requestsMeasured()],
+                cost: { certainty: "measured", money: zero },
+                ...common,
+            };
+        return failed
+            ? {
+                measurements: [
+                    { unit: "units", quantity: units(0n), certainty: "measured" },
+                    requestsMeasured(),
+                ],
+                cost: { certainty: "measured", money: zero },
+                ...common,
+            }
+            : {
+                measurements: [
+                    { unit: "units", quantity: units(1n), certainty: "estimated" },
+                    requestsMeasured(),
+                ],
+                cost: { certainty: "estimated", money: zero },
+                ...common,
+            };
+    },
+    requestId: (body) => {
+        const id = pointer(body, "/search_metadata/id");
+        return typeof id === "string" && id ? id : undefined;
+    },
+};

package/dist/serpapi/index.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderModule } from "../types.js";
+/** Provider B: no per-call cost, monthly plan, query auth. See docs/PROVIDERS.md section 5. */
+export declare const serpapi: ProviderModule;

package/dist/serpapi/index.js

@@ -0,0 +1,4 @@
+import { descriptor } from "./descriptor.js";
+import { extractors } from "./extractors.js";
+/** Provider B: no per-call cost, monthly plan, query auth. See docs/PROVIDERS.md section 5. */
+export const serpapi = { descriptor, extractors };

package/dist/testing/conformance.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderDescriptor } from "@usagekit/core";
+import type { Extractors } from "../types.js";
+import type { FixtureDirectory } from "../fixtures.js";
+/**
+ * Contract tests for one descriptor: it validates, every advertised operation has at least one
+ * fixture, and every fixture matches its operation and yields the expected receipt or parsed
+ * value. fixturesDir maps each fixture path to its parsed JSON, for example
+ * `import.meta.glob("./fixtures/**\/*.json", { eager: true, import: "default" })`, because web
+ * runtime packages cannot read directories.
+ */
+export declare function runDescriptorConformance(descriptor: ProviderDescriptor, extractors: Extractors, fixturesDir: FixtureDirectory): void;

package/dist/testing/conformance.js

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import { validateDescriptor } from "@usagekit/core";
+import { createCatalog } from "../catalog.js";
+import { loadFixtures, missingFixtures, verifyFixture } from "../fixtures.js";
+/**
+ * Contract tests for one descriptor: it validates, every advertised operation has at least one
+ * fixture, and every fixture matches its operation and yields the expected receipt or parsed
+ * value. fixturesDir maps each fixture path to its parsed JSON, for example
+ * `import.meta.glob("./fixtures/**\/*.json", { eager: true, import: "default" })`, because web
+ * runtime packages cannot read directories.
+ */
+export function runDescriptorConformance(descriptor, extractors, fixturesDir) {
+    describe(`descriptor ${descriptor.id}`, () => {
+        const fixtures = loadFixtures(fixturesDir);
+        const catalog = createCatalog({
+            providers: [{ descriptor, extractors }],
+            enabled: [descriptor.id],
+        });
+        test("validates without problems", () => {
+            expect(validateDescriptor(descriptor)).toEqual([]);
+        });
+        test("every advertised operation has a fixture", () => {
+            expect(missingFixtures(descriptor, fixtures)).toEqual([]);
+        });
+        test("every fixture belongs to this descriptor", () => {
+            expect(fixtures.filter((f) => f.provider !== descriptor.id).map((f) => f.path)).toEqual([]);
+        });
+        for (const fixture of fixtures)
+            test(`fixture ${fixture.operation}/${fixture.path.split("/").at(-1)}`, () => {
+                expect(verifyFixture(catalog, fixture)).toEqual([]);
+            });
+    });
+}

package/dist/testing/example.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderDescriptor } from "@usagekit/core";
+import type { Extractors, ProviderModule } from "../types.js";
+/**
+ * A synthetic descriptor that exercises every catalog rule: a base path, match precedence, plan
+ * and option axes, an overage row, a free probe. It is the template for new descriptors and is
+ * never enabled by hosts.
+ */
+export declare const exampleDescriptor: ProviderDescriptor;
+export declare const exampleExtractors: Extractors;
+export declare const exampleProvider: ProviderModule;

package/dist/testing/example.js

@@ -0,0 +1,146 @@
+import { listEstimate } from "../prices.js";
+import { moneyFromCents, requestsMeasured } from "../receipts.js";
+const source = "https://example.com/pricing";
+/**
+ * A synthetic descriptor that exercises every catalog rule: a base path, match precedence, plan
+ * and option axes, an overage row, a free probe. It is the template for new descriptors and is
+ * never enabled by hosts.
+ */
+export const exampleDescriptor = {
+    id: "example",
+    label: "Example provider",
+    upstream: "https://api.example.com/v1",
+    auth: { kind: "header", name: "X-Api-Key" },
+    billing: { unit: "units", cycle: "monthly_plan" },
+    plans: [
+        {
+            id: "basic",
+            label: "Basic",
+            cycle: "monthly_plan",
+            allowance: { unit: "units", value: 1000n },
+            allowanceMode: "hard",
+        },
+        {
+            id: "pro",
+            label: "Pro",
+            cycle: "monthly_plan",
+            allowance: { unit: "units", value: 5000n },
+            allowanceMode: "soft",
+        },
+        { id: "credits", label: "Credits", cycle: "prepaid", allowanceMode: "hard" },
+    ],
+    prices: [
+        { validFrom: "2026-01-01", operation: "search", plan: "basic", unit: "units", perUnit: "1" },
+        {
+            validFrom: "2026-01-01",
+            operation: "search",
+            plan: "basic",
+            option: { priority: "high" },
+            unit: "units",
+            perUnit: "2",
+        },
+        { validFrom: "2026-01-01", operation: "search", plan: "pro", unit: "units", perUnit: "1" },
+        {
+            validFrom: "2026-01-01",
+            operation: "search",
+            plan: "pro",
+            overage: true,
+            unit: "cents",
+            perUnit: "0.5000",
+        },
+        { validFrom: "2026-01-01", operation: "search", plan: "credits", unit: "units", perUnit: "1" },
+        { validFrom: "2026-01-01", operation: "search.images", unit: "cents", perUnit: "0.30" },
+        { validFrom: "2026-10-01", operation: "search.images", unit: "cents", perUnit: "0.40" },
+        { validFrom: "2026-01-01", operation: "items.get", unit: "cents", perUnit: "0.1" },
+        { validFrom: "2026-01-01", operation: "items.special", unit: "cents", perUnit: "0.2" },
+    ].map((row) => ({ ...row, source, checkedAt: "2026-09-25" })),
+    priceList: { kind: "static" },
+    operations: [
+        {
+            id: "search",
+            label: "Web search",
+            billable: true,
+            match: [{ method: "GET", path: "/search" }],
+            optionKeys: ["priority"],
+            costEvidence: "response",
+        },
+        {
+            id: "search.images",
+            label: "Image search",
+            billable: true,
+            match: [{ method: "GET", path: "/search", query: { engine: "images" } }],
+            costEvidence: "response",
+        },
+        {
+            id: "items.get",
+            label: "Item",
+            billable: true,
+            match: [{ method: "GET", path: "/items/:id" }],
+            costEvidence: "response",
+        },
+        {
+            id: "items.special",
+            label: "Special item",
+            billable: true,
+            match: [{ method: "GET", path: "/items/special" }],
+            costEvidence: "response",
+        },
+        {
+            id: "files",
+            label: "Files",
+            billable: true,
+            match: [{ method: "ANY", path: "/files/*" }],
+            costEvidence: "none",
+        },
+        {
+            id: "account",
+            label: "Account",
+            billable: false,
+            match: [{ method: "GET", path: "/account" }],
+            costEvidence: "none",
+        },
+    ],
+    balance: {
+        operation: "account",
+        fields: {
+            remaining: "/searches_left",
+            remainingUnit: "units",
+            allowance: "/searches_per_month",
+            used: "/used",
+            resetsAt: "/renews_on",
+            plan: "/plan",
+            accountIdentity: "/email",
+            rateLimitPerHour: "/hourly_limit",
+        },
+    },
+    billingExport: { kind: "none", granularity: "per-request", matchKey: "providerRequestId" },
+    docs: { pricing: source, api: "https://example.com/docs" },
+};
+export const exampleExtractors = {
+    estimate: listEstimate,
+    options: (operation, request) => {
+        const priority = new URL(request.url).searchParams.get("priority");
+        return operation.optionKeys?.includes("priority") && priority ? { priority } : {};
+    },
+    extract: (_operation, _request, response, body) => {
+        const b = (body ?? {});
+        const id = typeof b.id === "string" ? b.id : undefined;
+        return {
+            measurements: [requestsMeasured()],
+            cost: typeof b.cost_cents === "string"
+                ? { certainty: "measured", money: moneyFromCents(b.cost_cents) }
+                : { certainty: "unknown", money: null },
+            ...(id ? { providerRequestId: id } : {}),
+            cached: false,
+            failed: response.status >= 400,
+        };
+    },
+    requestId: (body) => {
+        const id = body?.id;
+        return typeof id === "string" ? id : undefined;
+    },
+};
+export const exampleProvider = {
+    descriptor: exampleDescriptor,
+    extractors: exampleExtractors,
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+/** Test harness and the synthetic example descriptor. Requires vitest. */
+export { runDescriptorConformance } from "./conformance.js";
+export { exampleDescriptor, exampleExtractors, exampleProvider } from "./example.js";

package/dist/testing/index.js

@@ -0,0 +1,3 @@
+/** Test harness and the synthetic example descriptor. Requires vitest. */
+export { runDescriptorConformance } from "./conformance.js";
+export { exampleDescriptor, exampleExtractors, exampleProvider } from "./example.js";

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+import type { BalanceSnapshot, BillingLine, PriceRow, ProviderDescriptor, ProviderOperation, Quantity, Receipt } from "@usagekit/core";
+/**
+ * A provider request as data. The body is already parsed (JSON value or text), so extractors
+ * stay synchronous and never consume a stream.
+ */
+export type ProviderRequest = {
+    method: string;
+    /** Absolute URL, or a path resolved against the descriptor's upstream. */
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    body?: unknown;
+};
+export type ProviderResponse = {
+    status: number;
+    headers?: Readonly<Record<string, string>>;
+};
+/** A receipt without identity and timestamps; the host wrapper adds id, occurredAt, recordedAt. */
+export type ReceiptDraft = Omit<Receipt, "id" | "supersedes" | "occurredAt" | "recordedAt">;
+export type EstimateInput = {
+    operation: ProviderOperation;
+    options: Readonly<Record<string, string>>;
+    plan?: string;
+    /** Past the plan allowance: only overage rows apply. */
+    overage?: boolean;
+    /** Rows valid at the catalog date, in descriptor order. */
+    prices: readonly PriceRow[];
+};
+/** The only code in a descriptor. Every function is pure and synchronous. */
+export type Extractors = {
+    /** 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. */
+    options(operation: ProviderOperation, request: ProviderRequest): Record<string, string>;
+    /** Receipt from the response; body is fully read. Returns unknown cost when evidence is absent. */
+    extract(operation: ProviderOperation, request: ProviderRequest, response: ProviderResponse, body: unknown): ReceiptDraft;
+    /** Provider request id for replay and reconciliation, when present. */
+    requestId(body: unknown): string | undefined;
+    /** Parse the balance probe body; without it the catalog reads the declared JSON pointers. */
+    balance?(body: unknown): BalanceSnapshot;
+    /** Parse a price-list endpoint body into PriceRow[] (for priceList.kind endpoint). */
+    priceList?(body: unknown, checkedAt: string): PriceRow[];
+    /** Parse a billing export into matchable lines. */
+    billingExport?(input: unknown): BillingLine[];
+};
+export type ProviderModule = {
+    descriptor: ProviderDescriptor;
+    extractors: Extractors;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@usagekit/providers",
+  "version": "0.4.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Provider descriptors, catalog, price tables, extractors, fixtures and probes.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./eslint": {
+      "types": "./dist/eslint.d.ts",
+      "import": "./dist/eslint.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "prepublishOnly": "node ../../scripts/publish-guard.mjs",
+    "prepack": "node ../../scripts/package-license.mjs"
+  },
+  "dependencies": {
+    "@usagekit/core": "0.4.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=5.0.1 <6",
+    "eslint": ">=9 <11"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  }
+}