scoutline 0.19.7 → 0.21.0

package/dist/providers/openalex/adapter.js

@@ -0,0 +1,313 @@
+/**
+ * OpenAlex Provider Adapter — science search + get via the works JSON API.
+ *
+ * Credential model (DESIGN D2 supplier table + D4b note): keyless by
+ * default (1000 credits/day), with the optional `OPENALEX_API_KEY`
+ * upgrade. `credentialEnvVars` is `["OPENALEX_API_KEY"]`; the cache
+ * fingerprint is `""` when keyless (keyless responses are
+ * user-independent) and the SHA-256 hex of the key otherwise (house
+ * method, brave/linkup precedent) — keyed upgrades re-partition
+ * (PRD AC-6b). The env flows through `create({ env })`, never the
+ * transport seam.
+ *
+ * Politeness (DESIGN D2 politeness bullet): the house
+ * `scoutline/${VERSION}` User-Agent rides every request; the
+ * `mailto=` query param rides whenever no api_key is present (the
+ * diagnostics probe included — D2 round-3 posture applies to the
+ * minimal wire call).
+ *
+ * Controls (DESIGN D7 table openalex column): `author`, `year`, and
+ * `type` are wire-consumed together on ONE works call
+ * (`filter=raw_author_name.search:`, `from/to_publication_date`,
+ * `type:`). `venue` is REJECTED at validate — probe-closed: OpenAlex
+ * has no name-based venue filter (`display_name.search` 400s) — honest
+ * UNSUPPORTED_OPTION, never accept-and-drop (PRD AC-3). The `type`
+ * VALUE is rewritten per the D7 round-2 translation table (chapter →
+ * book-chapter etc.); `conference-paper` is rejected v1 (D10
+ * type-vocabulary probe: the OpenAlex vocabulary carries no such
+ * value).
+ *
+ * Parsing (DESIGN D2/D3, PRD AC-7c/AC-7d): deterministic JSON field
+ * mapping with abstract_inverted_index reconstruction — one word per
+ * POSITION (a repeated word occupies each of its positions), so the
+ * output is token-entry-order independent. Absent supplier fields
+ * stay absent, never undefined-valued and never fabricated.
+ *
+ * Identifiers (DESIGN D10 ruling 3): bare DOI → `works/doi:<doi>`
+ * entity route; numeric PMID → `filter=ids.pmid:` search. The URL
+ * forms OpenAlex returns (`https://doi.org/…`, the pubmed URL form of
+ * ids.pmid) normalize to the bare house forms.
+ */
+import { createHash } from "node:crypto";
+import { parseScienceIdentifier, validateScienceGetRequest, validateScienceSearchRequest, } from "../../capabilities/science.js";
+import { ApiError, UnsupportedOptionError } from "../../lib/errors.js";
+import { fetchOpenalexJson, resolveOpenalexCredentials } from "./client.js";
+import { createOpenalexDiagnosticsCapability } from "./diagnostics.js";
+// ---------------------------------------------------------------------------
+// Wire mapping (DESIGN D7 table openalex column)
+// ---------------------------------------------------------------------------
+/**
+ * D7 round-2 translation table, openalex column: union `type` values
+ * map to OpenAlex wire literals. `conference-paper` is absent — the
+ * OpenAlex vocabulary carries no such value (D10 type-vocabulary
+ * probe), so it is rejected at validate, never silently narrowed.
+ */
+const TYPE_WIRE_LITERALS = Object.freeze({
+    article: "article",
+    preprint: "preprint",
+    chapter: "book-chapter",
+    dataset: "dataset",
+    review: "review",
+    other: "other",
+});
+/** Year control "2020" | "2018:2022" → from/to publication-date pair. */
+function yearFilterPair(year) {
+    const [from, to] = year.split(":");
+    return { from: `${from}-01-01`, to: `${to ?? from}-12-31` };
+}
+/** Search filters (D7 table) as one `filter=` param string. */
+function buildSearchFilter(query) {
+    const controls = query.controls ?? {};
+    const parts = [];
+    if (controls.author !== undefined) {
+        parts.push(`raw_author_name.search:${controls.author}`);
+    }
+    if (controls.year !== undefined) {
+        const { from, to } = yearFilterPair(controls.year);
+        parts.push(`from_publication_date:${from}`, `to_publication_date:${to}`);
+    }
+    if (controls.type !== undefined) {
+        const literal = TYPE_WIRE_LITERALS[controls.type];
+        if (literal !== undefined)
+            parts.push(`type:${literal}`);
+    }
+    return parts.join(",");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toOpenalexWork(value) {
+    return isRecord(value) ? value : undefined;
+}
+/**
+ * Deterministic abstract reconstruction (PRD AC-7c): one word per
+ * POSITION, token-entry-order independent. A repeated word occupying
+ * positions [0, 4] fills both slots; two parses of the same index are
+ * identical.
+ */
+function reconstructAbstract(index) {
+    if (index === null || index === undefined)
+        return undefined;
+    // Positions are collected, never used as array indexes (review):
+    // a hostile/huge position (e.g. 1e9) would allocate and scan a
+    // sparse array of that length, pinning the process.
+    const slots = new Map();
+    for (const [word, positions] of Object.entries(index)) {
+        for (const position of positions) {
+            if (Number.isSafeInteger(position) && position >= 0)
+                slots.set(position, word);
+        }
+    }
+    const text = [...slots.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([, word]) => word)
+        .join(" ");
+    // An EMPTY inverted index reconstructs to "" — that is an absent
+    // abstract (AC-7c), not an empty-string summary.
+    return text === "" ? undefined : text;
+}
+/** `https://doi.org/10.1038/...` → `10.1038/...`; null stays absent. */
+function bareDoi(doi) {
+    if (doi === null || doi === undefined || doi === "")
+        return undefined;
+    return doi.replace(/^https?:\/\/doi\.org\//i, "");
+}
+/** Pubmed URL form `https://pubmed.ncbi.nlm.nih.gov/23903748/` → `23903748`. */
+function barePmid(pmid) {
+    if (pmid === null || pmid === undefined || pmid === "")
+        return undefined;
+    const m = /(\d+)\/?$/.exec(pmid);
+    return m?.[1];
+}
+/**
+ * Map one OpenAlex work record to a `ScienceWork`. Absent supplier
+ * fields stay absent — keys are omitted, never set to undefined (the
+ * AC-7c honesty teeth: `Object.hasOwn(w, k) === false`), never
+ * fabricated.
+ */
+function mapWork(work) {
+    const identifiers = {};
+    const doi = bareDoi(work.doi ?? work.ids?.doi ?? null);
+    const pmid = barePmid(work.ids?.pmid ?? null);
+    if (doi !== undefined)
+        identifiers.doi = doi;
+    if (pmid !== undefined)
+        identifiers.pmid = pmid;
+    const location = work.primary_location ?? null;
+    const authors = (work.authorships ?? [])
+        .map((a) => a?.author?.display_name)
+        .filter((n) => typeof n === "string" && n !== "");
+    const summary = reconstructAbstract(work.abstract_inverted_index);
+    const pdfUrl = location?.pdf_url ?? undefined;
+    const venue = location?.source?.display_name ?? undefined;
+    const year = work.publication_year ?? undefined;
+    const citationCount = work.cited_by_count ?? undefined;
+    const openAccess = work.open_access?.is_oa ?? undefined;
+    const out = {
+        title: work.title ?? "",
+        url: location?.landing_page_url ?? work.id ?? "",
+    };
+    if (Object.keys(identifiers).length > 0)
+        out.identifiers = identifiers;
+    if (authors.length > 0)
+        out.authors = authors;
+    if (year !== undefined)
+        out.year = year;
+    if (venue !== undefined && venue !== "")
+        out.venue = venue;
+    if (summary !== undefined)
+        out.summary = summary;
+    if (citationCount !== undefined)
+        out.citationCount = citationCount;
+    if (pdfUrl !== undefined && pdfUrl !== "")
+        out.pdfUrl = pdfUrl;
+    if (openAccess !== undefined)
+        out.openAccess = openAccess;
+    if (work.type !== undefined && work.type !== null)
+        out.type = work.type;
+    if (work.language !== undefined && work.language !== null)
+        out.language = work.language;
+    return out;
+}
+/** Extract the `results` array (search) or accept a single work (get). */
+function openalexResults(doc) {
+    if (!isRecord(doc))
+        return [];
+    if (Array.isArray(doc["results"]))
+        return doc["results"];
+    return [doc];
+}
+// ---------------------------------------------------------------------------
+// Validation (shared validator + adapter-level control rulings)
+// ---------------------------------------------------------------------------
+function validateOpenalexSearchRequest(request) {
+    validateScienceSearchRequest(request);
+    const controls = request.controls ?? {};
+    if (controls.venue !== undefined) {
+        throw new UnsupportedOptionError("openalex", "science.search", "venue");
+    }
+    if (controls.type !== undefined && TYPE_WIRE_LITERALS[controls.type] === undefined) {
+        throw new UnsupportedOptionError("openalex", "science.search", "type");
+    }
+}
+function validateOpenalexGetRequest(request) {
+    // Shared grammar first: out-of-bare-grammar identifiers (prefixed
+    // `doi:…`, free text) throw ValidationError (DESIGN D1).
+    validateScienceGetRequest(request);
+    // D10 ruling 3: openalex serves DOI and PMID gets (arXiv ids route to
+    // the arxiv adapter instead).
+    if (parseScienceIdentifier(request.identifier) === "arxiv") {
+        throw new UnsupportedOptionError("openalex", "science.get", "identifier");
+    }
+}
+// ---------------------------------------------------------------------------
+// Science capability
+// ---------------------------------------------------------------------------
+/**
+ * Cache identity (DESIGN D4b note + PRD AC-6b): keyless `""`
+ * (user-independent responses) or the SHA-256 hex of the active
+ * `OPENALEX_API_KEY` — keyed upgrades re-partition.
+ */
+function openalexCacheIdentity(env, capability, request) {
+    const { apiKey } = resolveOpenalexCredentials(env);
+    return {
+        supplier: "openalex",
+        capability,
+        credentialFingerprint: apiKey === undefined ? "" : createHash("sha256").update(apiKey).digest("hex"),
+        request,
+    };
+}
+function createOpenalexScienceCapability(options) {
+    const { env, transport } = options;
+    const deps = { ...transport, env };
+    const search = {
+        validate: validateOpenalexSearchRequest,
+        cacheIdentity(request) {
+            return openalexCacheIdentity(env, "science.search", request);
+        },
+        async invoke(request, signal) {
+            search.validate(request);
+            const filter = buildSearchFilter(request);
+            const params = { search: request.query.trim() };
+            if (filter !== "")
+                params["filter"] = filter;
+            const doc = await fetchOpenalexJson(params, deps, signal);
+            return openalexResults(doc).map((r) => mapWork(toOpenalexWork(r) ?? {}));
+        },
+    };
+    const get = {
+        validate: validateOpenalexGetRequest,
+        cacheIdentity(request) {
+            return openalexCacheIdentity(env, "science.get", request);
+        },
+        async invoke(request, signal) {
+            get.validate(request);
+            const kind = parseScienceIdentifier(request.identifier);
+            const doc = kind === "doi"
+                ? await fetchOpenalexJson({}, deps, signal, `doi:${request.identifier}`)
+                : await fetchOpenalexJson({ filter: `ids.pmid:${request.identifier}` }, deps, signal);
+            const results = openalexResults(doc);
+            const first = results[0];
+            if (kind !== "doi" || first === undefined || !isRecord(first)) {
+                if (first === undefined || !isRecord(first)) {
+                    throw new ApiError(`OpenAlex returned no work for ${request.identifier}`, 404);
+                }
+            }
+            return mapWork(first);
+        },
+    };
+    return { search, get };
+}
+/**
+ * OpenAlex capability set — the science trio plus diagnostics (D2
+ * round-3). `quota` never appears (quota dashboard filter exclusion),
+ * with or without the optional key.
+ */
+const OPENALEX_CAPABILITIES = new Set([
+    "science.search",
+    "science.get",
+    "diagnostics",
+]);
+/**
+ * Build the OpenAlex Provider Descriptor. Keyless-by-default with an
+ * optional upgrade key: `isConfigured` is true for the no-capability
+ * form (doctor) and the science trio + diagnostics — never `quota` or
+ * non-science capabilities. `create()` is side-effect-free; transport
+ * and credential resolution run per capability call.
+ */
+export function createOpenalexDescriptor(dependencies) {
+    const transport = dependencies?.transport;
+    return {
+        id: "openalex",
+        isConfigured(_env, capabilityId) {
+            if (capabilityId === undefined)
+                return true;
+            return OPENALEX_CAPABILITIES.has(capabilityId);
+        },
+        capabilities() {
+            return OPENALEX_CAPABILITIES;
+        },
+        create(context) {
+            return {
+                id: "openalex",
+                science: createOpenalexScienceCapability({ env: context.env, transport }),
+                diagnostics: createOpenalexDiagnosticsCapability({
+                    transport,
+                    env: context.env,
+                }),
+            };
+        },
+        credentialEnvVars: ["OPENALEX_API_KEY"],
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/openalex/adapter.js.map

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

package/dist/providers/openalex/client.d.ts

@@ -0,0 +1,18 @@
+import type { ProviderQuotaFetch } from "../types.js";
+export declare const OPENALEX_WORKS_URL = "https://api.openalex.org/works";
+/** Injectable transport dependencies (fetch, timers). */
+export interface OpenalexTransportDeps {
+    readonly fetch?: ProviderQuotaFetch;
+    readonly setTimeout?: typeof setTimeout;
+    readonly clearTimeout?: typeof clearTimeout;
+}
+/** Credential resolved per invocation from the injected env. */
+export interface OpenalexCredentials {
+    /** `OPENALEX_API_KEY` when present; keyless otherwise. */
+    readonly apiKey?: string;
+}
+export declare function resolveOpenalexCredentials(env: NodeJS.ProcessEnv): OpenalexCredentials;
+export declare function fetchOpenalexJson(params: Record<string, string>, deps?: OpenalexTransportDeps & {
+    readonly env?: NodeJS.ProcessEnv;
+}, signal?: AbortSignal, path?: string): Promise<unknown>;
+//# sourceMappingURL=client.d.ts.map

package/dist/providers/openalex/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/openalex/client.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKtD,eAAO,MAAM,kBAAkB,mCAAmC,CAAC;AAMnE,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;CAC7C;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,mBAAmB,CAGtF;AAwED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,GAAE,qBAAqB,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,EACvE,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,SAAK,GACR,OAAO,CAAC,OAAO,CAAC,CAkElB"}

package/dist/providers/openalex/client.js

@@ -0,0 +1,159 @@
+/**
+ * OpenAlex direct HTTP transport.
+ *
+ * GETs against `https://api.openalex.org/works` (DESIGN D2 supplier
+ * table) consuming JSON. OpenAlex is keyless-by-default with an
+ * optional `OPENALEX_API_KEY` upgrade: with no key the request carries
+ * the politeness `mailto=` query param (house contact address, D2
+ * politeness bullet); with a key the `api_key=` query param replaces
+ * it (OpenAlex consumes the key as a query param, not a header). The
+ * house `USER_AGENT` rides every request either way.
+ *
+ * Boundary rules (ARCHITECTURE.md §2), cloning the arXiv client shape:
+ *   - May import normalized errors and the provider fetch seam.
+ *   - Must NOT perform response field normalization — the Adapter owns
+ *     parsing. This module returns the parsed JSON document as unknown.
+ */
+import pkg from "../../../package.json" with { type: "json" };
+import { ApiError, AuthError, NetworkError, QuotaError, TimeoutError } from "../../lib/errors.js";
+import { getGlobalFetch } from "../types.js";
+const { version: VERSION } = pkg;
+export const OPENALEX_WORKS_URL = "https://api.openalex.org/works";
+const DEFAULT_TIMEOUT_MS = 30000;
+const USER_AGENT = `scoutline/${VERSION}`;
+/** House contact address for the OpenAlex polite pool (D2 politeness). */
+const OPENALEX_MAILTO = "scoutline@localhost";
+export function resolveOpenalexCredentials(env) {
+    const apiKey = env["OPENALEX_API_KEY"];
+    return apiKey === undefined || apiKey === "" ? {} : { apiKey };
+}
+/**
+ * Layer 1 — HTTP-status mapping, before the body is consumed. 401/403
+ * → AuthError; 408/504 → TimeoutError; other 4xx/5xx → ApiError with
+ * the real status preserved for the shared retry classifier.
+ */
+function mapStatusError(status, timeoutMs) {
+    if (status === 401 || status === 403) {
+        return new AuthError("OpenAlex rejected the request");
+    }
+    if (status === 408 || status === 504) {
+        return new TimeoutError(timeoutMs);
+    }
+    if (status === 429) {
+        return new QuotaError("OpenAlex rate-limited — keyless budget; a free key raises the limit (see `scoutline init`)");
+    }
+    if (status === 503) {
+        // Remedy (owner ruling): anonymous search may be paused under load —
+        // the free key via `scoutline init` restores it. The class stays
+        // ApiError (the mapping pin) — only the message carries the remedy.
+        return new ApiError("OpenAlex request failed (anonymous search may be paused under load — a free API key via `scoutline init` restores it)", status);
+    }
+    return new ApiError("OpenAlex request failed", status);
+}
+/** Same transport-error normalization contract as the arXiv client. */
+function normalizeTransportError(error, timeoutMs) {
+    if (error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof QuotaError ||
+        error instanceof TimeoutError) {
+        return error;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+        return new TimeoutError(timeoutMs);
+    }
+    return new NetworkError("OpenAlex network error");
+}
+/**
+ * Core GET. `params` carries OpenAlex-native query parameters (search,
+ * filter, per-page — the Adapter maps Provider-neutral science
+ * requests into these); `path` addresses an entity route for
+ * identifier-addressed gets (e.g. `doi:10.1038/...`). Returns the
+ * parsed JSON document. No internal retry — shared execution owns
+ * retry policy.
+ */
+/**
+ * Percent-encode one entity-route path segment, preserving `/` at the
+ * caller. Encodes the URL-delimiter characters (`?`, `#`) and a stray
+ * `%` (keeps the segment unambiguous); leaves the `doi:` prefix colon
+ * and DOI-legal punctuation readable.
+ */
+function encodePathSegment(segment) {
+    // Dot-only segments are double-encoded (review): `new URL`
+    // normalizes an unencoded `..` away (`/works/../x` → `/works/x`),
+    // silently addressing the WRONG entity. %252E survives URL parsing
+    // as the literal segment `..`.
+    if (segment === "." || segment === "..") {
+        return segment.replaceAll(".", "%252E");
+    }
+    return segment.replace(/[?#%]/g, (c) => encodeURIComponent(c));
+}
+export async function fetchOpenalexJson(params, deps = {}, signal, path = "") {
+    const f = deps.fetch ?? getGlobalFetch();
+    const setT = deps.setTimeout ?? setTimeout;
+    const clearT = deps.clearTimeout ?? clearTimeout;
+    const { apiKey } = resolveOpenalexCredentials(deps.env ?? {});
+    // Entity-route path segments are percent-encoded (review): a DOI
+    // suffix containing `?` or `#` would otherwise be truncated into the
+    // query/fragment by `new URL`. `/` separators are preserved, and the
+    // `doi:` prefix colon stays readable.
+    const url = new URL(`${OPENALEX_WORKS_URL}${path ? `/${path.replace(/^\/+/, "").split("/").map(encodePathSegment).join("/")}` : ""}`);
+    for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+    }
+    // Politeness (D2): mailto whenever keyless; api_key replaces it when
+    // the upgrade key is present (never both).
+    if (apiKey !== undefined) {
+        url.searchParams.set("api_key", apiKey);
+    }
+    else {
+        url.searchParams.set("mailto", OPENALEX_MAILTO);
+    }
+    // A pre-aborted caller signal must not reach the transport (review):
+    // reject before the fetch is invoked at all.
+    if (signal?.aborted) {
+        throw new TimeoutError(DEFAULT_TIMEOUT_MS);
+    }
+    const controller = new AbortController();
+    const timeoutId = setT(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    const abortWithExternal = () => controller.abort();
+    if (signal !== undefined) {
+        if (signal.aborted) {
+            controller.abort();
+        }
+        else {
+            signal.addEventListener("abort", abortWithExternal, { once: true });
+        }
+    }
+    try {
+        const res = await f(url, {
+            method: "GET",
+            headers: { "User-Agent": USER_AGENT },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            await res.text().catch(() => { });
+            throw mapStatusError(res.status, DEFAULT_TIMEOUT_MS);
+        }
+        try {
+            return await res.json();
+        }
+        catch (err) {
+            // The timeout stays armed through body consumption; an abort here
+            // is the injected timeout firing, not a malformed payload.
+            if (controller.signal.aborted)
+                throw err;
+            throw new ApiError("OpenAlex returned a malformed response", 500);
+        }
+    }
+    catch (err) {
+        throw normalizeTransportError(err, DEFAULT_TIMEOUT_MS);
+    }
+    finally {
+        if (signal !== undefined) {
+            signal.removeEventListener("abort", abortWithExternal);
+        }
+        clearT(timeoutId);
+        controller.abort();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/providers/openalex/client.js.map

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

package/dist/providers/openalex/diagnostics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenAlex Diagnostics Capability.
+ *
+ * Keyless bounded probe (DESIGN D2 round-3 ruling): doctor probes
+ * every always-configured science supplier, so the OpenAlex probe is
+ * ONE minimal keyless wire call on the works endpoint (`per-page=1`)
+ * — never a full search. The politeness posture applies to it too:
+ * house UA plus the `mailto=` param whenever no api_key is present.
+ * When `diagOptions.probe` is false, `invoke` resolves immediately
+ * without touching the network.
+ */
+import type { DiagnosticsCapability } from "../../capabilities/diagnostics.js";
+import { type OpenalexTransportDeps } from "./client.js";
+export interface OpenalexDiagnosticsCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly transport?: OpenalexTransportDeps;
+}
+export declare function createOpenalexDiagnosticsCapability(options: OpenalexDiagnosticsCapabilityOptions): DiagnosticsCapability;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/providers/openalex/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/providers/openalex/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAqB,MAAM,mCAAmC,CAAC;AAElG,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAO5E,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;CAC5C;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,qBAAqB,CAevB"}

package/dist/providers/openalex/diagnostics.js

@@ -0,0 +1,25 @@
+import { createProbeErrorNormalizer, STANDARD_PROBE_PASS_THROUGH } from "../../lib/probe-errors.js";
+import { fetchOpenalexJson } from "./client.js";
+const normalizeProbeError = createProbeErrorNormalizer({
+    passThrough: STANDARD_PROBE_PASS_THROUGH,
+    fallbackMessage: "OpenAlex diagnostics probe failed",
+});
+export function createOpenalexDiagnosticsCapability(options) {
+    const { env, transport } = options;
+    return {
+        async invoke(diagOptions) {
+            if (!diagOptions.probe)
+                return;
+            try {
+                // One minimal keyless wire call on the works endpoint. The
+                // request parameter is `per-page` (review) — `per_page` is only
+                // response metadata the server ignores.
+                await fetchOpenalexJson({ "per-page": "1" }, { ...transport, env });
+            }
+            catch (error) {
+                throw normalizeProbeError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/providers/openalex/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/providers/openalex/diagnostics.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACpG,OAAO,EAAE,iBAAiB,EAA8B,MAAM,aAAa,CAAC;AAE5E,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;IACrD,WAAW,EAAE,2BAA2B;IACxC,eAAe,EAAE,mCAAmC;CACrD,CAAC,CAAC;AAOH,MAAM,UAAU,mCAAmC,CACjD,OAA6C;IAE7C,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACnC,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,WAA8B;YACzC,IAAI,CAAC,WAAW,CAAC,KAAK;gBAAE,OAAO;YAC/B,IAAI,CAAC;gBACH,2DAA2D;gBAC3D,gEAAgE;gBAChE,wCAAwC;gBACxC,MAAM,iBAAiB,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;YACtE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/providers/perplexity/adapter.d.ts

@@ -8,10 +8,12 @@
  * structured results with titles, URLs, snippets, and dates — far richer
  * than mapping chat completions to citations.
  *
- * Research uses the Sonar Chat Completions endpoint with the
- * `sonar-deep-research` model, which is designed for comprehensive
- * report synthesis. The response includes `search_results[]` with
- * structured source data (title, url, date, snippet).
+ * Research uses the Agent API (POST /v1/agent) with the `high`
+ * preset — the official successor to `sonar-deep-research` on the
+ * Sonar chat-completions endpoint (sunset 2026-09-27, #107). The
+ * response carries an `output[]` trace: `message` items hold the
+ * report text, `search_results` items hold structured sources
+ * (title, url, date, snippet) — one item per search round.
  *
  * Reader is intentionally omitted: Perplexity does not offer a
  * dedicated webpage extraction API.
@@ -22,10 +24,10 @@
  *     results[].url     -> url
  *     results[].snippet -> summary
  *     results[].date    -> date
- *   Research (/chat/completions):
- *     choices[0].message.content -> report
- *     search_results[].title/url -> sources[]
- *     citations[] (fallback)     -> sources[]
+ *   Research (/v1/agent, preset "high"):
+ *     output[].message.content[].text -> report
+ *     output[].search_results.results[] -> sources[] (union across
+ *       search rounds, deduped by URL, first occurrence wins)
  *
  * Control mapping (SearchControls → Search API params):
  *   domain      -> search_domain_filter: [domain]

package/dist/providers/perplexity/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/perplexity/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EACf,kBAAkB,EAClB,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAIV,gBAAgB,EAGjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAa/E,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAiGrB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,qBAAa,iBAAkB,YAAW,eAAe;IAOrD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAgB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C,YACmB,OAAO,EAAE,eAAe,EACzC,IAAI,GAAE,6BAAkC,EAgJzC;CACF;AAED,wBAAgB,0BAA0B,IAAI,kBAAkB,CAU/D"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/perplexity/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EACf,kBAAkB,EAClB,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAIV,gBAAgB,EAGjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAa/E,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAmGrB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AA0CD,qBAAa,iBAAkB,YAAW,eAAe;IAOrD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAgB;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAE5C,YACmB,OAAO,EAAE,eAAe,EACzC,IAAI,GAAE,6BAAkC,EAwHzC;CACF;AAED,wBAAgB,0BAA0B,IAAI,kBAAkB,CAU/D"}