@rackbops/docket-types 0.4.0 → 0.6.0

package/dist/want-sources.d.ts

@@ -0,0 +1,67 @@
+import { type Fetch } from "@rackbops/docket-core";
+/**
+ * The want-list watcher's sources (category 2, plan 1.2 row 2; rackbops-bot-plugins#83): where a
+ * wanted thing's listings come from, behind one port so the type (wantlist.ts) knows none of
+ * them. Two read listings:
+ *
+ * - `page` (here): a listing or search page the owner pasted (roshne, 2026-10-04, "Pages too"), read
+ *   through the fenced Fetch port as `/price` reads a product page, and only its structured data --
+ *   JSON-LD `ItemList`s of products and standalone `Product`s. No guessing at HTML: a page without
+ *   them yields nothing, and the owner is told.
+ * - `bgg` (want-bgg.ts): BoardGameGeek's marketplace, through its XML API, off until BGG approves
+ *   roshne's application and `TRACKER_BGG_TOKEN` is set.
+ *
+ * eBay is a third answer, not a source: the tracker never reads eBay (no API, no pages); `/want`
+ * hands the owner an eBay search to save on eBay, whose own alerts do the watching (the tracker plugin's `/want`).
+ */
+export interface Listing {
+    /** Stable for one listing: its URL without the fragment, for `page`; `bgg:<link>` for BGG. */
+    id: string;
+    title: string;
+    url: string;
+    price?: number;
+    currency?: string;
+    condition?: string;
+    seller?: string;
+}
+export type SourceId = "page" | "bgg";
+export declare const SOURCE_IDS: readonly SourceId[];
+export interface Source {
+    id: SourceId;
+    /** The listings at `target` now; throws `SourceMiss` for a read that counts as a miss. */
+    search(target: string, fetch: Fetch | undefined): Promise<Listing[]>;
+}
+/** A read that found nothing usable (an error page, no structured data, a busy API): the type counts it. */
+export declare class SourceMiss extends Error {
+    name: string;
+}
+/** The source cannot be read at all as set up (BGG refusing the token): a miss the owner should hear about. */
+export declare class SourceUnavailableError extends SourceMiss {
+    name: string;
+}
+export declare const MAX_LISTINGS = 100;
+/** The key a listing is remembered by: a digest of its id, so the state stays small whatever the URLs. */
+export declare function listingKey(id: string): string;
+/**
+ * A request header that is a directive to the host's Fetch port, never sent: any hop to eBay is
+ * refused. The page source's reads carry it, so a pasted page that redirects to eBay is not read
+ * either (roshne's rule: eBay's own saved-search alerts cover eBay; the tracker never reads it).
+ * A host's Fetch adapter must honour it and strip it.
+ */
+export declare const NEVER_EBAY = "x-tracker-never-ebay";
+/** eBay's own hosts (and its short links). */
+export declare function isEbayHost(host: string): boolean;
+/**
+ * The listings in a page's JSON-LD: each `ItemList`'s elements (a `ListItem`'s `item`, or the
+ * element itself) and each standalone product, in page order, without repeats. A product with no
+ * address of its own is the page itself (a product page). Pure.
+ */
+export declare function listingsFromJsonLd(html: string, pageUrl: string): Listing[];
+/** `listingsFromJsonLd`, and how many `ItemList`s the page declares: an empty one is a search with no results, not an unreadable page. */
+export declare function readListings(html: string, pageUrl: string): {
+    listings: Listing[];
+    lists: number;
+};
+/** The `page` source: the owner's page through the fenced Fetch port, structured data only. */
+export declare const pageSource: Source;
+//# sourceMappingURL=want-sources.d.ts.map

package/dist/want-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"want-sources.d.ts","sourceRoot":"","sources":["../src/want-sources.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAIzD;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,OAAO;IACtB,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAA;AACrC,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAoB,CAAA;AAE9D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,QAAQ,CAAA;IACZ,0FAA0F;IAC1F,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;CACrE;AAED,4GAA4G;AAC5G,qBAAa,UAAW,SAAQ,KAAK;IAC1B,IAAI,SAAe;CAC7B;AAED,+GAA+G;AAC/G,qBAAa,sBAAuB,SAAQ,UAAU;IAC3C,IAAI,SAA2B;CACzC;AAED,eAAO,MAAM,YAAY,MAAM,CAAA;AAM/B,0GAA0G;AAC1G,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,yBAAyB,CAAA;AAEhD,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAkFD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAE3E;AAED,0IAA0I;AAC1I,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuCxC;AAED,+FAA+F;AAC/F,eAAO,MAAM,UAAU,EAAE,MAsBxB,CAAA"}

package/dist/want-sources.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { clean } from "@rackbops/docket-core";
+import { jsonLdBlocks, priceFromJson } from "./extract.js";
+import { safeUrl } from "./research-answer.js";
+export const SOURCE_IDS = ["page", "bgg"];
+/** A read that found nothing usable (an error page, no structured data, a busy API): the type counts it. */
+export class SourceMiss extends Error {
+    name = "SourceMiss";
+}
+/** The source cannot be read at all as set up (BGG refusing the token): a miss the owner should hear about. */
+export class SourceUnavailableError extends SourceMiss {
+    name = "SourceUnavailableError";
+}
+export const MAX_LISTINGS = 100;
+const TITLE_CHARS = 150;
+const CONDITION_CHARS = 40;
+const SELLER_CHARS = 80;
+const MAX_DEPTH = 8;
+/** The key a listing is remembered by: a digest of its id, so the state stays small whatever the URLs. */
+export function listingKey(id) {
+    return createHash("sha256").update(id).digest("hex").slice(0, 32);
+}
+/**
+ * A request header that is a directive to the host's Fetch port, never sent: any hop to eBay is
+ * refused. The page source's reads carry it, so a pasted page that redirects to eBay is not read
+ * either (roshne's rule: eBay's own saved-search alerts cover eBay; the tracker never reads it).
+ * A host's Fetch adapter must honour it and strip it.
+ */
+export const NEVER_EBAY = "x-tracker-never-ebay";
+/** eBay's own hosts (and its short links). */
+export function isEbayHost(host) {
+    return /(^|\.)ebay\.[a-z]{2,3}(\.[a-z]{2})?$/i.test(host.replace(/\.$/, ""));
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function typesOf(node) {
+    const t = node["@type"];
+    const all = Array.isArray(t) ? t : [t];
+    return all
+        .filter((x) => typeof x === "string")
+        .map((x) => x.replace(/^https?:\/\/schema\.org\//, ""));
+}
+const PRODUCT_TYPES = new Set([
+    "Product",
+    "IndividualProduct",
+    "ProductModel",
+    "ProductGroup",
+    "Book",
+    "Game",
+    "VideoGame",
+    "Vehicle",
+]);
+function text(v, max) {
+    if (typeof v === "string")
+        return clean(v, max, true);
+    if (isObj(v) && typeof v.name === "string")
+        return clean(v.name, max, true);
+    return "";
+}
+/** schema.org's condition as a word: `https://schema.org/UsedCondition` is "used". */
+function conditionOf(v) {
+    const raw = text(v, 200);
+    const m = /(New|Used|Refurbished|Damaged)Condition$/i.exec(raw);
+    return m ? (m[1] ?? "").toLowerCase() : clean(raw, CONDITION_CHARS, true);
+}
+function firstOffer(offers) {
+    if (Array.isArray(offers))
+        return offers.find(isObj) ?? null;
+    return isObj(offers) ? offers : null;
+}
+/**
+ * Query parameters a shop adds per view or per search (Shopify's `_pos`/`_sid`/`_ss`, Google's
+ * `srsltid`, the `utm_*` family and the click ids): dropped from a listing's address, so one listing
+ * keeps one id from poll to poll and is not sent again as new.
+ */
+const PER_VIEW = /^(utm_[a-z]+|_pos|_sid|_ss|_psq|srsltid|gclid|gbraid|wbraid|fbclid|msclkid|mc_cid|mc_eid|pf_rd_[a-z]+|pd_rd_[a-z]+)$/i;
+function absolute(raw, base) {
+    if (typeof raw !== "string" || raw.trim() === "")
+        return null;
+    try {
+        const u = new URL(raw.trim(), base);
+        u.hash = "";
+        for (const key of [...u.searchParams.keys()])
+            if (PER_VIEW.test(key))
+                u.searchParams.delete(key);
+        return safeUrl(u.toString());
+    }
+    catch {
+        return null;
+    }
+}
+/** One listing from a product node, or null without a name or a usable address. */
+function listingOf(node, base, fallbackUrl) {
+    const title = text(node.name, TITLE_CHARS);
+    const offer = firstOffer(node.offers);
+    const url = absolute(node.url, base) ?? absolute(fallbackUrl, base) ?? absolute(offer?.url, base);
+    if (!title || !url)
+        return null;
+    const price = priceFromJson(node.offers ?? null);
+    const condition = conditionOf(offer?.itemCondition ?? node.itemCondition);
+    const seller = text(offer?.seller, SELLER_CHARS);
+    return {
+        id: url,
+        title,
+        url,
+        ...(price ? { price: price.value } : {}),
+        ...(price?.currency ? { currency: price.currency } : {}),
+        ...(condition ? { condition } : {}),
+        ...(seller ? { seller } : {}),
+    };
+}
+/**
+ * The listings in a page's JSON-LD: each `ItemList`'s elements (a `ListItem`'s `item`, or the
+ * element itself) and each standalone product, in page order, without repeats. A product with no
+ * address of its own is the page itself (a product page). Pure.
+ */
+export function listingsFromJsonLd(html, pageUrl) {
+    return readListings(html, pageUrl).listings;
+}
+/** `listingsFromJsonLd`, and how many `ItemList`s the page declares: an empty one is a search with no results, not an unreadable page. */
+export function readListings(html, pageUrl) {
+    let lists = 0;
+    const out = [];
+    const seen = new Set();
+    const add = (l) => {
+        if (!l || seen.has(l.id) || out.length >= MAX_LISTINGS)
+            return;
+        seen.add(l.id);
+        out.push(l);
+    };
+    const walk = (node, depth) => {
+        if (depth > MAX_DEPTH || out.length >= MAX_LISTINGS)
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                walk(n, depth + 1);
+            return;
+        }
+        if (!isObj(node))
+            return;
+        const types = typesOf(node);
+        if (types.includes("ItemList")) {
+            lists++;
+            const elements = Array.isArray(node.itemListElement)
+                ? node.itemListElement
+                : [node.itemListElement];
+            for (const el of elements) {
+                if (!isObj(el))
+                    continue;
+                const item = isObj(el.item) ? el.item : el;
+                if (typesOf(item).includes("ItemList"))
+                    walk(item, depth + 1);
+                else
+                    add(listingOf(item, pageUrl, el.url ?? (typeof el.item === "string" ? el.item : undefined)));
+            }
+        }
+        else if (types.some((t) => PRODUCT_TYPES.has(t))) {
+            add(listingOf(node, pageUrl, pageUrl));
+        }
+        if (node["@graph"] !== undefined)
+            walk(node["@graph"], depth + 1);
+        if (isObj(node.mainEntity))
+            walk(node.mainEntity, depth + 1);
+    };
+    for (const block of jsonLdBlocks(html))
+        walk(block, 0);
+    return { listings: out, lists };
+}
+/** The `page` source: the owner's page through the fenced Fetch port, structured data only. */
+export const pageSource = {
+    id: "page",
+    async search(target, fetch) {
+        if (!fetch)
+            throw new SourceMiss("this bot reads no pages");
+        let body;
+        try {
+            const response = await fetch.get(target, { [NEVER_EBAY]: "1" });
+            if (response.status !== 200)
+                throw new SourceMiss(`HTTP ${response.status}`);
+            body = response.body;
+        }
+        catch (err) {
+            if (err instanceof SourceMiss)
+                throw err;
+            // The cause is kept: `/want`'s first read tells a refused page from one that failed this once.
+            throw new SourceMiss(`the read failed: ${err instanceof Error ? err.message : String(err)}`, {
+                cause: err,
+            });
+        }
+        const { listings, lists } = readListings(body, target);
+        // A search with nothing for sale (the usual state of a want) still declares its list.
+        if (listings.length === 0 && lists === 0)
+            throw new SourceMiss("no listings in the page's structured data");
+        return listings;
+    },
+};
+//# sourceMappingURL=want-sources.js.map

package/dist/want-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"want-sources.js","sourceRoot":"","sources":["../src/want-sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,KAAK,EAAc,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AA8B9C,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAQ9D,4GAA4G;AAC5G,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,GAAG,YAAY,CAAA;CAC7B;AAED,+GAA+G;AAC/G,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IAC3C,IAAI,GAAG,wBAAwB,CAAA;CACzC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAA;AAC/B,MAAM,WAAW,GAAG,GAAG,CAAA;AACvB,MAAM,eAAe,GAAG,EAAE,CAAA;AAC1B,MAAM,YAAY,GAAG,EAAE,CAAA;AACvB,MAAM,SAAS,GAAG,CAAC,CAAA;AAEnB,0GAA0G;AAC1G,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,sBAAsB,CAAA;AAEhD,8CAA8C;AAC9C,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,uCAAuC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAA;AAC9E,CAAC;AAGD,MAAM,KAAK,GAAG,CAAC,CAAU,EAAa,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAEjG,SAAS,OAAO,CAAC,IAAU;IACzB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;IACvB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACtC,OAAO,GAAG;SACP,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;SACjD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC,CAAA;AAC3D,CAAC;AAED,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,SAAS;IACT,mBAAmB;IACnB,cAAc;IACd,cAAc;IACd,MAAM;IACN,MAAM;IACN,WAAW;IACX,SAAS;CACV,CAAC,CAAA;AAEF,SAAS,IAAI,CAAC,CAAU,EAAE,GAAW;IACnC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IACrD,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IAC3E,OAAO,EAAE,CAAA;AACX,CAAC;AAED,sFAAsF;AACtF,SAAS,WAAW,CAAC,CAAU;IAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACxB,MAAM,CAAC,GAAG,2CAA2C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC/D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED,SAAS,UAAU,CAAC,MAAe;IACjC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;IAC5D,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,QAAQ,GACZ,uHAAuH,CAAA;AAEzH,SAAS,QAAQ,CAAC,GAAY,EAAE,IAAY;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAC7D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAA;QACnC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAA;QACX,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAChG,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,SAAS,SAAS,CAAC,IAAU,EAAE,IAAY,EAAE,WAAoB;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACrC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;IACjG,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAC/B,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAA;IAChD,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,EAAE,aAAa,IAAI,IAAI,CAAC,aAAa,CAAC,CAAA;IACzE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,CAAA;IAChD,OAAO;QACL,EAAE,EAAE,GAAG;QACP,KAAK;QACL,GAAG;QACH,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9B,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAe;IAC9D,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAA;AAC7C,CAAC;AAED,0IAA0I;AAC1I,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,OAAe;IAEf,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,MAAM,GAAG,GAAc,EAAE,CAAA;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAiB,EAAE,EAAE;QAChC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,YAAY;YAAE,OAAM;QAC9D,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACd,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACb,CAAC,CAAA;IACD,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,KAAa,EAAQ,EAAE;QAClD,IAAI,KAAK,GAAG,SAAS,IAAI,GAAG,CAAC,MAAM,IAAI,YAAY;YAAE,OAAM;QAC3D,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,IAAI;gBAAE,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;YACxC,OAAM;QACR,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAM;QACxB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,KAAK,EAAE,CAAA;YACP,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC;gBAClD,CAAC,CAAC,IAAI,CAAC,eAAe;gBACtB,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;YAC1B,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;oBAAE,SAAQ;gBACxB,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;gBAC1C,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;;oBAE3D,GAAG,CACD,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CACxF,CAAA;YACL,CAAC;QACH,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;QACxC,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QACjE,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;IAC9D,CAAC,CAAA;IACD,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IACtD,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,EAAE,EAAE,MAAM;IACV,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK;QACxB,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAA;QAC3D,IAAI,IAAY,CAAA;QAChB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;YAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;gBAAE,MAAM,IAAI,UAAU,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;YAC5E,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAA;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,UAAU;gBAAE,MAAM,GAAG,CAAA;YACxC,+FAA+F;YAC/F,MAAM,IAAI,UAAU,CAAC,oBAAoB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE;gBAC3F,KAAK,EAAE,GAAG;aACX,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACtD,sFAAsF;QACtF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YACtC,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAA;QACnE,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF,CAAA"}

package/dist/wantjudge.d.ts

@@ -0,0 +1,111 @@
+import { type JobSpec, type TaskType } from "@rackbops/docket-core";
+import { type Listing, type Source, type SourceId } from "./want-sources.js";
+import { type WantConfig, type WantState } from "./wantlist.js";
+/**
+ * The judged want-list watch (category 2, plan 5.4 and item 63; rackbops-bot-plugins#83): the
+ * watcher (wantlist.ts) with the model looking at each new listing before it is DMed -- is it
+ * the thing wanted, and what does the listing's own page show about the seller. "The model used only
+ * to judge new candidates" (5.4): the source is read in plain code, and a model Job is made only when
+ * that read finds listings not told before.
+ *
+ * A type of its own because a task's lane is its type's: on the execute lane, so a judged watch
+ * waits behind other model runs and stops while its owner is at a budget ceiling, and the plain
+ * watch keeps the notify lane's promptness. Two runs per batch, through the state:
+ *
+ * 1. the scheduled run's `prepare` reads the source; with nothing new it ends there, uncharged
+ *    (`NoJob`); with new listings it keeps them as `pending` and asks for a follow-up;
+ * 2. that follow-up's `prepare` (or the next scheduled run's, if it comes first and no retry is
+ *    waiting) turns `pending` into the judge Job, and `finish` maps its verdicts back onto
+ *    `pending` by number. A follow-up never reads the source, so follow-ups never chain.
+ *
+ * `pending` lives in the state, not in memory, so a Job collected after a restart still has the
+ * listings it was about. The judge may open only listings on the watch's own site (`WebFetch`
+ * scoped to the pasted page's host or BGG's, never eBay's; no web search), so a seller is vetted from the source's own data (item
+ * 63), as signals with what the page showed, never as a verdict about a real person (plan section 6).
+ * A listing the model calls "no" is not DMed but is kept as a finding, so `/task history` shows
+ * it; one with no verdict is shown as "maybe". When judging fails for good, the listings go out
+ * unchecked: an alert never waits on the model for longer than its retries.
+ *
+ * The Job may not search the web or read the runner's files (`Read`, `Glob`, `Grep`, `LS`).
+ * Failures retry as the scout's do (`MAX_TRIES`, `auth_failed` an hour later); a usage limit never
+ * reaches `finish`. Model output is data: each field is capped, cleaned and made inert.
+ */
+export declare const FITS: readonly ["match", "maybe", "no"];
+export type Fit = (typeof FITS)[number];
+/** Proposed, like the scout's (item 61): a short look at up to 20 pages. */
+export declare const JUDGE_MAX_TURNS = 12;
+export declare const JUDGE_MAX_BUDGET_USD = 0.5;
+export declare const JUDGE_TIMEOUT_MS = 300000;
+/** How long past its due time a waiting retry is left to its own follow-up before a scheduled run takes it. */
+export declare const RETRY_GRACE_MS: number;
+export interface JudgeState extends WantState {
+    /** Listings read and not told yet, waiting for the model's look; at most `MAX_NEW_PER_RUN`. */
+    pending: Listing[];
+    /** Failed tries of the current look. */
+    failures: number;
+    /** When the waiting retry is due (ISO), while `failures` > 0. */
+    retryAt?: string;
+}
+export interface JudgeVerdict {
+    fit: Fit;
+    why: string;
+    seller: string;
+}
+export declare const JUDGE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly verdicts: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly n: {
+                        readonly type: "integer";
+                        readonly description: "The listing's number, as given.";
+                    };
+                    readonly fit: {
+                        readonly type: "string";
+                        readonly enum: readonly ["match", "maybe", "no"];
+                    };
+                    readonly why: {
+                        readonly type: "string";
+                    };
+                    readonly seller: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["n", "fit", "why"];
+            };
+            readonly maxItems: 20;
+        };
+    };
+    readonly required: readonly ["verdicts"];
+};
+export declare function judgeState(value: unknown): JudgeState;
+/**
+ * The hosts the judge may open: only the watch's own -- the pasted page's host (or it with or
+ * without `www.`), or BGG's -- and only where a pending listing is on it. That host is one the
+ * tracker's own fenced reads reach every poll (the host's Fetch port checks its address after the name lookup);
+ * a host a listing merely names is never granted, since the runner sits on roshne's network and a
+ * shop's data could name a private one (`nas.lan`). A listing elsewhere is judged from its own
+ * text. Never an address, never eBay.
+ */
+export declare function judgeHosts(pending: readonly Listing[], config: WantConfig): string[];
+/** The judge Job: the want, the listings numbered (shop text, inert, marked as data), and the rules. */
+export declare function judgeJob(title: string, config: WantConfig, pending: readonly Listing[]): JobSpec;
+/** The verdicts by listing number (1-based, up to `count`), the first for each; null when it is no answer. */
+export declare function parseVerdicts(value: unknown, count: number): Map<number, JudgeVerdict> | null;
+/** The DM: the listings worth a look, best first, each with the model's note and the seller signals. */
+export declare function renderJudged(title: string, taskId: string, shown: readonly {
+    l: Listing;
+    v: JudgeVerdict;
+}[], passed: number, config: WantConfig): string;
+/** The DM when judging failed for good: the listings unchecked, so the alert still goes out. */
+export declare function renderUnchecked(title: string, taskId: string, pending: readonly Listing[], reason: string, config: WantConfig): string;
+export interface JudgeOptions {
+    /** How a deferred BGG read waits before its one second try (tests pass a no-op). */
+    wait?: (ms: number) => Promise<void>;
+}
+/** The judged type over `sources` (the plain watch's); BGG's spacing is waited out once, on this background lane. */
+export declare function wantjudgeType(sources: Partial<Record<SourceId, Source>>, o?: JudgeOptions): TaskType<WantConfig>;
+//# sourceMappingURL=wantjudge.d.ts.map

package/dist/wantjudge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wantjudge.d.ts","sourceRoot":"","sources":["../src/wantjudge.ts"],"names":[],"mappings":"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"}