@deadair/plugin-sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,1153 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/boundary.json.safe.ts
+var JSON_SAFE_PAYLOAD_TYPES = [
+  "PluginConnectionResult",
+  "PluginPermissions",
+  "NetworkPermissionHost",
+  "NetworkPermissionFromConfig",
+  "PluginGrantRequest",
+  "ConfigField",
+  "ConfigFieldOption",
+  "ConfigFieldColumn",
+  "PluginManifest",
+  "ProviderTrack",
+  "ProviderPlaylist",
+  "ProviderStream",
+  "TrackFetchSession",
+  "TrackFetchRequest",
+  "SearchTracksOptions",
+  "ListPlaylistsOptions",
+  "GetPlaylistTracksOptions",
+  "PlaybackState",
+  "TrackRef",
+  "ArtistRef",
+  "AlbumRef",
+  "ExternalId",
+  "ExternalLink",
+  "SourceDocument",
+  "TrackEnrichment",
+  "ArtistEnrichment",
+  "AlbumEnrichment",
+  "SpeechRequest",
+  "SpeechVoice",
+  "LlmMessage",
+  "LlmToolDeclaration",
+  "LlmToolCall",
+  "LlmUsage",
+  "LlmRequest",
+  "LlmResult",
+  "LlmModelInfo",
+  "AnalysisRef",
+  "AudioJoin",
+  "AudioOverlay",
+  "TrackCuePoints",
+  "TrackLoudness",
+  "TrackTaggedLoudness",
+  "TrackAnalysis",
+  "ChartDescriptor",
+  "ChartQuery",
+  "ChartEntry",
+  "NewsFeedDescriptor",
+  "NewsQuery",
+  "NewsItem",
+  "SimilarArtist",
+  "ArtistTrack",
+  "SearchQuery",
+  "SearchResult",
+  "WeatherQuery",
+  "WeatherConditions",
+  "WeatherDay",
+  "WeatherReading",
+  "ScrobblePlay",
+  "ScrobbleRejection",
+  "ScrobbleResult"
+];
+var BOUNDARY_METHOD_TYPES = [
+  "PluginLogger",
+  "PluginStorage",
+  "PluginSecrets",
+  "PluginConfigAccess",
+  "PluginOAuth",
+  "PluginEvents",
+  "PluginTrackFetcher",
+  "PluginHost",
+  "PluginLifecycle",
+  "MusicProviderCatalog",
+  "MusicProviderStream",
+  "MusicProviderSteer",
+  "MusicProviderOAuth",
+  "MusicProvider",
+  "EnrichmentProvider",
+  "SpeechPluginInstance",
+  "LlmPluginInstance",
+  "AnalysisProvider",
+  "MixerProvider",
+  "ChartsProvider",
+  "NewsProvider",
+  "SimilarityProvider",
+  "SearchProvider",
+  "WeatherProvider",
+  "ScrobbleProvider"
+];
+var BOUNDARY_LIVE_OBJECT_TYPES = [
+  // `signal`: the invocation's own `AbortSignal`, watched by `host.fetch` and
+  // passed on by the plugin to anything else that takes one.
+  "HostFetchInit",
+  // `audio`: the engine's response body, usually forwarded straight through,
+  // so the bytes are never held whole on either side of the call.
+  "SpeechHandle",
+  // `audio`: the same thing one capability over, on the `mixer` side. A joined production is the
+  // longest single piece of audio the station ever makes, so holding it whole
+  // is the one thing this must not do.
+  "JoinedAudio",
+  // `text`: the words as the model produces them, and `result`: a promise that
+  // settles when it stops. The stream is what lets the host hold its single
+  // model slot until the generation really ends rather than until the call
+  // returns. `LlmResult` is the payload half, and it is JSON-safe.
+  "LlmHandle"
+];
+
+// src/capabilities/analysis.ts
+var ANALYSIS_SCHEMA_VERSION = 1;
+
+// src/capabilities/enrichment.ts
+var ENRICHMENT_MATCH_KEY_ISRC = "isrc";
+var ENRICHMENT_MATCH_KEY_ARTIST_TITLE = "artist-title";
+var KNOWN_ENRICHMENT_MATCH_KEYS = [
+  ENRICHMENT_MATCH_KEY_ISRC,
+  ENRICHMENT_MATCH_KEY_ARTIST_TITLE
+];
+
+// src/plugin.error.ts
+var PLUGIN_ERROR_CODES = [
+  "auth",
+  "config",
+  "not_found",
+  "forbidden",
+  "rate_limited",
+  "timeout",
+  "unavailable",
+  "unsupported",
+  "upstream",
+  "internal"
+];
+var RESOURCE_SCOPED_CODES = /* @__PURE__ */ new Set([
+  "not_found",
+  "forbidden",
+  "unsupported"
+]);
+function isResourceScopedCode(code) {
+  return RESOURCE_SCOPED_CODES.has(code);
+}
+__name(isResourceScopedCode, "isResourceScopedCode");
+var RETRYABLE_BY_CODE = {
+  auth: false,
+  config: false,
+  not_found: false,
+  forbidden: false,
+  unsupported: false,
+  rate_limited: true,
+  timeout: true,
+  unavailable: true,
+  upstream: true,
+  internal: true
+};
+var PLUGIN_ERROR_BRAND = /* @__PURE__ */ Symbol.for("deadair.plugin-error/v1");
+var PluginError = class extends Error {
+  static {
+    __name(this, "PluginError");
+  }
+  /** @internal Recognition marker for a foreign copy. See {@link PLUGIN_ERROR_BRAND}. */
+  [PLUGIN_ERROR_BRAND] = true;
+  /** What went wrong, in host vocabulary. Defaults to `internal`; set it with {@link withCode}. */
+  code = "internal";
+  /** Whether repeating the call could plausibly succeed. See {@link RETRYABLE_BY_CODE}. */
+  retryable = RETRYABLE_BY_CODE.internal;
+  /** How long to wait before retrying, when the upstream said so (`Retry-After`). */
+  retryAfterMs;
+  /**
+   * The upstream's HTTP status, for logs and for plugin-internal branching.
+   * Diagnostic only: the host never forwards it as its own response status.
+   */
+  upstreamStatus;
+  constructor(message, options) {
+    super(message, options);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "PluginError";
+  }
+  /** Classifies the failure, and resets `retryable` to the default for that code. */
+  withCode(code) {
+    this.code = code;
+    this.retryable = RETRYABLE_BY_CODE[code];
+    return this;
+  }
+  /**
+   * Attaches the upstream's retry advice. Saying "wait this long and try
+   * again" is itself a statement that a retry is worth making, so this marks
+   * the failure retryable regardless of what the code defaults to.
+   */
+  withRetry(retryAfterMs2) {
+    this.retryable = true;
+    this.retryAfterMs = retryAfterMs2;
+    return this;
+  }
+  withUpstreamStatus(upstreamStatus) {
+    this.upstreamStatus = upstreamStatus;
+    return this;
+  }
+};
+var isPluginError = /* @__PURE__ */ __name((error) => {
+  return error instanceof PluginError;
+}, "isPluginError");
+function isForeignPluginError(value) {
+  if (typeof value !== "object" || value === null) return false;
+  return value[PLUGIN_ERROR_BRAND] === true;
+}
+__name(isForeignPluginError, "isForeignPluginError");
+function toPluginError(error, fallback = "internal") {
+  if (isPluginError(error)) return error;
+  if (isForeignPluginError(error)) {
+    const known = typeof error.code === "string" && PLUGIN_ERROR_CODES.includes(error.code);
+    const message2 = typeof error.message === "string" ? error.message : String(error);
+    const adopted = new PluginError(message2, {
+      cause: error
+    }).withCode(known ? error.code : fallback);
+    if (typeof error.retryAfterMs === "number" && Number.isFinite(error.retryAfterMs)) adopted.withRetry(error.retryAfterMs);
+    if (typeof error.upstreamStatus === "number" && Number.isFinite(error.upstreamStatus)) adopted.withUpstreamStatus(error.upstreamStatus);
+    return adopted;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new PluginError(message, {
+    cause: error
+  }).withCode(fallback);
+}
+__name(toPluginError, "toPluginError");
+var errorText = /* @__PURE__ */ __name((error) => error instanceof Error ? error.message : String(error), "errorText");
+
+// src/capabilities/llm.ts
+async function collectGeneration(handle, signal) {
+  const reader = handle.text.getReader();
+  void handle.result.catch(() => void 0);
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+      const chunk = await Promise.race([
+        reader.read(),
+        aborted(signal)
+      ]);
+      if (chunk === ABORTED) break;
+      if (chunk.done) break;
+    }
+  } finally {
+    if (signal?.aborted) {
+      void reader.cancel().catch(() => void 0);
+    } else {
+      reader.releaseLock();
+    }
+  }
+  if (signal?.aborted) {
+    throw new PluginError("the generation was stopped before it finished").withCode("unavailable");
+  }
+  return handle.result;
+}
+__name(collectGeneration, "collectGeneration");
+var ABORTED = /* @__PURE__ */ Symbol("aborted");
+function aborted(signal) {
+  if (signal === void 0) return new Promise(() => void 0);
+  if (signal.aborted) return Promise.resolve(ABORTED);
+  return new Promise((resolve) => signal.addEventListener("abort", () => resolve(ABORTED), {
+    once: true
+  }));
+}
+__name(aborted, "aborted");
+
+// src/capabilities/speech.ts
+var SPEECH_CUES = [
+  "laugh",
+  "chuckle",
+  "sigh",
+  "gasp",
+  "cough",
+  "clear throat",
+  "sniff",
+  "groan"
+];
+function cuesIn(text2) {
+  return [
+    ...text2.matchAll(cuePattern())
+  ].map((match) => match[1].toLowerCase());
+}
+__name(cuesIn, "cuesIn");
+function withoutCues(text2, keep = []) {
+  const kept = /* @__PURE__ */ new Set([
+    ...keep
+  ]);
+  return text2.replace(cuePattern(), (match, cue) => kept.has(cue.toLowerCase()) ? match : " ").replace(/[^\S\n]{2,}/g, " ").replace(/[^\S\n]+([.,!?;:])/g, "$1").trim();
+}
+__name(withoutCues, "withoutCues");
+var cuePattern = /* @__PURE__ */ __name(() => new RegExp(`\\[(${[
+  ...SPEECH_CUES
+].sort((left, right) => right.length - left.length).join("|")})\\]`, "gi"), "cuePattern");
+
+// src/plugin.http.ts
+var MAX_UPSTREAM_MESSAGE = 200;
+function truncateUpstreamMessage(message) {
+  return message.length > MAX_UPSTREAM_MESSAGE ? `${message.slice(0, MAX_UPSTREAM_MESSAGE)}\u2026` : message;
+}
+__name(truncateUpstreamMessage, "truncateUpstreamMessage");
+function upstreamField(body, pick) {
+  if (!body) return void 0;
+  let value;
+  try {
+    value = pick(JSON.parse(body));
+  } catch {
+    return void 0;
+  }
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+__name(upstreamField, "upstreamField");
+function retryAfterMs(header) {
+  if (header === null || header === void 0) return void 0;
+  const seconds = Number(header.trim());
+  if (!Number.isFinite(seconds) || seconds < 0) return void 0;
+  return seconds * 1e3;
+}
+__name(retryAfterMs, "retryAfterMs");
+function pluginCodeForStatus(status) {
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "unavailable";
+  return "upstream";
+}
+__name(pluginCodeForStatus, "pluginCodeForStatus");
+function upstreamDetail(status, statusText, reason) {
+  return [
+    `HTTP ${status}`,
+    statusText,
+    reason
+  ].filter((part) => part).join(" ");
+}
+__name(upstreamDetail, "upstreamDetail");
+var HOST_FETCH_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD"
+];
+function hostFetchMethod(method) {
+  const upper = (method ?? "GET").toUpperCase();
+  return HOST_FETCH_METHODS.find((candidate) => candidate === upper);
+}
+__name(hostFetchMethod, "hostFetchMethod");
+function headersToRecord(headers) {
+  const record2 = {};
+  headers.forEach((value, name) => {
+    record2[name.toLowerCase()] = value;
+  });
+  return record2;
+}
+__name(headersToRecord, "headersToRecord");
+
+// src/html.text.ts
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  ndash: "\u2013",
+  mdash: "\u2014",
+  hellip: "\u2026",
+  lsquo: "\u2018",
+  rsquo: "\u2019",
+  ldquo: "\u201C",
+  rdquo: "\u201D"
+};
+function decodeEntities(value) {
+  return value.replace(/&(#x?[0-9a-f]+|\w+);/gi, (whole, body) => {
+    if (body.startsWith("#")) {
+      const code = body[1]?.toLowerCase() === "x" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code > 0 && code <= 1114111 ? String.fromCodePoint(code) : whole;
+    }
+    return NAMED_ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+__name(decodeEntities, "decodeEntities");
+function plainText(raw, maxChars) {
+  const stripped = decodeEntities(raw.replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
+  if (stripped.length === 0) return void 0;
+  return maxChars === void 0 ? stripped : truncateWords(stripped, maxChars);
+}
+__name(plainText, "plainText");
+function truncateWords(value, maxChars) {
+  if (value.length <= maxChars) return value;
+  const cut = value.slice(0, maxChars);
+  const lastSpace = cut.lastIndexOf(" ");
+  return `${(lastSpace > maxChars - 40 ? cut.slice(0, lastSpace) : cut).trimEnd()}\u2026`;
+}
+__name(truncateWords, "truncateWords");
+var SENTENCE_END = /[.!?]["'”’)\]]*\s+(?=["'“‘(]?[A-Z0-9])/g;
+var ABBREVIATIONS = /\b(mr|mrs|ms|dr|prof|rev|st|jr|sr|gov|sen|rep|lt|sgt|col|gen|capt|jan|feb|mar|apr|jun|jul|aug|sept|sep|oct|nov|dec|no|vs|approx|est|inc|ltd|co|dept|univ|u\.s|u\.k)$/i;
+var endsSentence = /* @__PURE__ */ __name((value, at) => !ABBREVIATIONS.test(value.slice(Math.max(0, at - 12), at)), "endsSentence");
+function firstSentence(value) {
+  const text2 = value.trim();
+  SENTENCE_END.lastIndex = 0;
+  for (let match = SENTENCE_END.exec(text2); match !== null; match = SENTENCE_END.exec(text2)) {
+    const stop = match.index;
+    if (endsSentence(text2, stop)) return text2.slice(0, stop + 1).trim();
+  }
+  return text2;
+}
+__name(firstSentence, "firstSentence");
+function truncateSentences(value, maxChars) {
+  if (value.length <= maxChars) return value;
+  let lastStop = -1;
+  SENTENCE_END.lastIndex = 0;
+  for (let match = SENTENCE_END.exec(value); match !== null; match = SENTENCE_END.exec(value)) {
+    if (match.index >= maxChars) break;
+    if (endsSentence(value, match.index)) lastStop = match.index;
+  }
+  if (lastStop <= 0) return truncateWords(value, maxChars);
+  return value.slice(0, lastStop + 1).trimEnd();
+}
+__name(truncateSentences, "truncateSentences");
+var wordsIn = /* @__PURE__ */ __name((value) => value.split(/\s+/).filter(Boolean).length, "wordsIn");
+var closersIn = /* @__PURE__ */ __name((boundary) => boundary.slice(1).trimEnd(), "closersIn");
+function sentencesWithin(value, maxWords) {
+  const text2 = value.trim();
+  if (wordsIn(text2) <= maxWords) return text2;
+  let fits;
+  SENTENCE_END.lastIndex = 0;
+  for (let match = SENTENCE_END.exec(text2); match !== null; match = SENTENCE_END.exec(text2)) {
+    if (!endsSentence(text2, match.index)) continue;
+    const ending = text2.slice(0, match.index + 1 + closersIn(match[0]).length);
+    if (wordsIn(ending) > maxWords) break;
+    fits = ending;
+  }
+  return fits;
+}
+__name(sentencesWithin, "sentencesWithin");
+
+// src/article.parse.ts
+var ARTICLE_MAX_CHARS = 2e3;
+var MIN_PARAGRAPH_CHARS = 60;
+var FURNITURE = /<(script|style|noscript|template|svg|figure|figcaption|aside|nav|header|footer|form)\b[^>]*>[\s\S]*?<\/\1>/gi;
+var FURNITURE_CLASSES = /<(div|section|span|p|ul|ol)\b[^>]*(?:class|id|aria-label)="[^"]*\b(caption|credit|byline|promo|newsletter|related|recirc|sidebar|share|social|advert|subscribe|paywall|tags?)\b[^"]*"[^>]*>[\s\S]*?<\/\1>/gi;
+var REFERENCE_APPARATUS = [
+  // `{{cite web |…}}`, `{{efn|…}}`. One level and non-nesting, which is the
+  // safe direction: a nested template leaves its outer braces behind as two
+  // characters rather than eating the sentence after it.
+  [
+    /\{\{[^{}]*\}\}/g,
+    ""
+  ],
+  // `[ 1 ]`, `[12]`.
+  [
+    /\[\s*\d+\s*\]/g,
+    ""
+  ],
+  // `[ citation needed ]`, `[ edit ]`.
+  [
+    /\[\s*(?:citation needed|clarification needed|edit|note \d+|update)\s*\]/gi,
+    ""
+  ],
+  // `[[BBC]]` and `[[David Bowie|Bowie]]`: the only one that keeps its match,
+  // because what is inside is the words a reader sees rather than apparatus.
+  [
+    /\[\[(?:[^[\]|]*\|)?([^[\]|]*)\]\]/g,
+    "$1"
+  ]
+];
+var SPONSOR_OPENERS = [
+  "a message from",
+  "a note from our sponsor",
+  "advertisement",
+  "advertorial",
+  "paid content",
+  "paid for by",
+  "paid partnership",
+  "presented by",
+  "promoted by",
+  "sponsored",
+  "sponsored by",
+  "sponsored content",
+  "sponsored survey",
+  "support for this",
+  "support comes from",
+  "this post is sponsored"
+];
+function opensWithASponsor(text2) {
+  const said = text2.toLowerCase();
+  return SPONSOR_OPENERS.some((opener) => {
+    if (!said.startsWith(opener)) return false;
+    const next = said.charAt(opener.length);
+    return next === "" || /[\s:;,.\u2013\u2014-]/.test(next);
+  });
+}
+__name(opensWithASponsor, "opensWithASponsor");
+var CONTAINERS = [
+  /<article\b[^>]*>([\s\S]*?)<\/article>/i,
+  /<main\b[^>]*>([\s\S]*?)<\/main>/i
+];
+var PARAGRAPH = /<p\b[^>]*>([\s\S]*?)<\/p>/gi;
+function extractArticle(html, maxChars = ARTICLE_MAX_CHARS) {
+  const cleaned = html.replace(FURNITURE, " ").replace(FURNITURE_CLASSES, " ");
+  const body = CONTAINERS.map((pattern) => pattern.exec(cleaned)?.[1]).find((found) => found !== void 0) ?? cleaned;
+  const paragraphs = [];
+  for (const match of body.matchAll(PARAGRAPH)) {
+    const text2 = withoutApparatus(plainText(match[1] ?? ""));
+    if (text2 === void 0 || text2.length < MIN_PARAGRAPH_CHARS) continue;
+    if (opensWithASponsor(text2)) continue;
+    if (!paragraphs.includes(text2)) paragraphs.push(text2);
+  }
+  if (paragraphs.length === 0) return void 0;
+  return truncateSentences(paragraphs.join(" "), maxChars);
+}
+__name(extractArticle, "extractArticle");
+function withoutApparatus(text2) {
+  if (text2 === void 0) return void 0;
+  let stripped = text2;
+  for (const [pattern, replacement] of REFERENCE_APPARATUS) stripped = stripped.replace(pattern, replacement);
+  const tidied = stripped.replace(/\s+/g, " ").replace(/\s+([,.;:!?])/g, "$1").trim();
+  return tidied.length === 0 ? void 0 : tidied;
+}
+__name(withoutApparatus, "withoutApparatus");
+async function fetchArticle(host, url, init, options) {
+  const response = await host.fetch(url, init);
+  if (!response.ok) {
+    await response.body?.cancel();
+    const error = new PluginError(`article request failed: ${upstreamDetail(response.status, response.statusText)}`).withCode(pluginCodeForStatus(response.status));
+    error.upstreamStatus = response.status;
+    const advice = retryAfterMs(response.headers.get("retry-after"));
+    if (advice !== void 0) error.withRetry(advice);
+    throw error;
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!/\b(text\/html|application\/xhtml\+xml)\b/i.test(contentType)) {
+    await response.body?.cancel();
+    return void 0;
+  }
+  return extractArticle(await response.text(), options?.maxChars);
+}
+__name(fetchArticle, "fetchArticle");
+
+// src/define.plugin.ts
+function definePlugin(manifest, factory) {
+  return {
+    manifest,
+    factory
+  };
+}
+__name(definePlugin, "definePlugin");
+
+// src/feed.parse.ts
+import { XMLParser } from "fast-xml-parser";
+var FEED_SUMMARY_MAX_CHARS = 500;
+var parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  removeNSPrefix: true,
+  trimValues: true,
+  // A guid of `12345` is an id, not a number, and a `<title>2024</title>` is a
+  // title. Every field here is read as text, so parsing any of it as a number
+  // only produces a value whose `.trim` is missing.
+  parseTagValue: false,
+  parseAttributeValue: false
+});
+function parseFeed(xml) {
+  let document;
+  try {
+    document = parser.parse(xml);
+  } catch {
+    return {
+      items: []
+    };
+  }
+  if (!isRecord(document)) return {
+    items: []
+  };
+  const rss = record(document.rss);
+  const rdf = record(document.RDF);
+  const atom = record(document.feed);
+  const channel = record(rss?.channel) ?? record(rdf?.channel) ?? atom;
+  if (channel === void 0) return {
+    items: []
+  };
+  const entries = [
+    ...asArray(record(rss?.channel)?.item),
+    ...asArray(rdf?.item),
+    ...asArray(atom?.entry)
+  ];
+  const feed = {
+    items: entries.flatMap((entry) => isRecord(entry) ? readItem(entry) ?? [] : [])
+  };
+  const title = speakable(channel.title);
+  if (title !== void 0) feed.title = title;
+  const homeUrl = readLink(channel.link);
+  if (homeUrl !== void 0) feed.homeUrl = homeUrl;
+  return feed;
+}
+__name(parseFeed, "parseFeed");
+async function fetchFeed(host, url, init) {
+  const response = await host.fetch(url, init);
+  if (!response.ok) {
+    await response.body?.cancel();
+    const error = new PluginError(`feed request failed: ${upstreamDetail(response.status, response.statusText)}`).withCode(pluginCodeForStatus(response.status));
+    error.upstreamStatus = response.status;
+    const advice = retryAfterMs(response.headers.get("retry-after"));
+    if (advice !== void 0) error.withRetry(advice);
+    throw error;
+  }
+  return parseFeed(await response.text());
+}
+__name(fetchFeed, "fetchFeed");
+function readItem(entry) {
+  const title = speakable(entry.title);
+  if (title === void 0) return void 0;
+  const url = readLink(entry.link);
+  const publishedAt = readDate(entry.pubDate ?? entry.published ?? entry.date ?? entry.updated ?? entry.issued);
+  const summary = plainText2(entry.description ?? entry.summary ?? entry.encoded ?? entry.content);
+  const author = readAuthor(entry.author ?? entry.creator);
+  const categories = readCategories(entry.category);
+  const item = {
+    id: readId(entry, title, publishedAt, url),
+    title
+  };
+  if (summary !== void 0) item.summary = summary;
+  if (url !== void 0) item.url = url;
+  if (publishedAt !== void 0) item.publishedAt = publishedAt;
+  if (author !== void 0) item.author = author;
+  if (categories.length > 0) item.categories = categories;
+  return item;
+}
+__name(readItem, "readItem");
+function readId(entry, title, publishedAt, url) {
+  return text(entry.guid) ?? text(entry.id) ?? url ?? `hash:${hash(`${title}\0${publishedAt ?? ""}`)}`;
+}
+__name(readId, "readId");
+function readLink(value) {
+  const candidates = asArray(value);
+  for (const candidate of candidates) {
+    if (typeof candidate === "string") return trimmed(candidate);
+    if (!isRecord(candidate)) continue;
+    const rel = text(candidate["@_rel"]);
+    if (rel !== void 0 && rel !== "alternate") continue;
+    const href = text(candidate["@_href"]) ?? text(candidate["#text"]);
+    if (href !== void 0) return href;
+  }
+  return void 0;
+}
+__name(readLink, "readLink");
+function readDate(value) {
+  const raw = text(value);
+  if (raw === void 0) return void 0;
+  const at = new Date(raw);
+  return Number.isNaN(at.getTime()) ? void 0 : at.toISOString();
+}
+__name(readDate, "readDate");
+function readAuthor(value) {
+  const first = asArray(value)[0];
+  if (typeof first === "string") return trimmed(first);
+  if (!isRecord(first)) return void 0;
+  return text(first.name) ?? text(first["#text"]);
+}
+__name(readAuthor, "readAuthor");
+function readCategories(value) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const candidate of asArray(value)) {
+    const name = typeof candidate === "string" ? trimmed(candidate) : isRecord(candidate) ? text(candidate["@_term"]) ?? text(candidate["#text"]) : void 0;
+    if (name !== void 0) seen.add(name);
+  }
+  return [
+    ...seen
+  ];
+}
+__name(readCategories, "readCategories");
+function plainText2(value) {
+  const raw = text(value);
+  return raw === void 0 ? void 0 : plainText(raw, FEED_SUMMARY_MAX_CHARS);
+}
+__name(plainText2, "plainText");
+function hash(value) {
+  let accumulated = 2166136261;
+  for (let at = 0; at < value.length; at += 1) {
+    accumulated ^= value.charCodeAt(at);
+    accumulated = Math.imul(accumulated, 16777619);
+  }
+  return (accumulated >>> 0).toString(16).padStart(8, "0");
+}
+__name(hash, "hash");
+function asArray(value) {
+  if (value === void 0 || value === null) return [];
+  return Array.isArray(value) ? value : [
+    value
+  ];
+}
+__name(asArray, "asArray");
+var isRecord = /* @__PURE__ */ __name((value) => typeof value === "object" && value !== null && !Array.isArray(value), "isRecord");
+var record = /* @__PURE__ */ __name((value) => isRecord(value) ? value : void 0, "record");
+var trimmed = /* @__PURE__ */ __name((value) => value.trim().length === 0 ? void 0 : value.trim(), "trimmed");
+function text(value) {
+  if (typeof value === "string") return trimmed(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (isRecord(value)) return text(value["#text"]);
+  return void 0;
+}
+__name(text, "text");
+var speakable = /* @__PURE__ */ __name((value) => {
+  const raw = text(value);
+  return raw === void 0 ? void 0 : plainText(raw);
+}, "speakable");
+
+// src/match.text.ts
+var PUNCTUATION = /[^\p{L}\p{N}\s]/gu;
+var PARENTHETICAL = /[([{][^)\]}]*[)\]}]/g;
+function normalize(value) {
+  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase().replace(PUNCTUATION, " ").replace(/\s+/g, " ").trim();
+}
+__name(normalize, "normalize");
+function baseForm(value) {
+  return normalize(value.replace(PARENTHETICAL, " ").split(/\s+[-–—]\s+/)[0] ?? value);
+}
+__name(baseForm, "baseForm");
+
+// src/plugin.api.version.ts
+var PLUGIN_API_VERSION = "1.0.0";
+
+// src/plugin.base.ts
+var Plugin = class {
+  static {
+    __name(this, "Plugin");
+  }
+  currentHost;
+  disposers = [];
+  /**
+   * The host, once `init` has run.
+   *
+   * A getter rather than a field so the failure is a sentence naming the
+   * plugin instead of a `TypeError` from somewhere three calls deeper.
+   *
+   * @throws {PluginError} `internal` when read before `init` or after
+   *   `dispose`. Both are host bugs rather than operator ones, which is what
+   *   that code means.
+   */
+  get host() {
+    if (this.currentHost === void 0) {
+      throw new PluginError(`${this.constructor.name} was used before init() or after dispose()`).withCode("internal");
+    }
+    return this.currentHost;
+  }
+  /**
+   * Registers something to undo when this plugin unloads.
+   *
+   * Call it next to the setup it undoes, which is the whole point: a
+   * `clearInterval` written beside its `setInterval` is one that cannot drift
+   * away from it as the file grows.
+   */
+  register(disposer) {
+    this.disposers.push(disposer);
+  }
+  /** {@link Plugin.register} for the common case. Works for `setTimeout` and `setInterval` alike. */
+  registerTimer(timer) {
+    this.register(() => clearTimeout(timer));
+  }
+  /** Your setup. Called once, after `this.host` is available and before any capability method. */
+  onLoad() {
+    return Promise.resolve();
+  }
+  /**
+   * Anything left to undo that `register` could not express, such as dropping
+   * a cache. Runs after every registered disposer.
+   */
+  onUnload() {
+    return Promise.resolve();
+  }
+  async init(host) {
+    this.currentHost = host;
+    await this.onLoad();
+  }
+  /**
+   * Undoes everything, in reverse.
+   *
+   * Every disposer runs even if an earlier one throws, because one broken
+   * undo must not strand the rest: the failure is logged and the walk
+   * continues. `onUnload` runs afterwards for the same reason it exists, and
+   * `this.host` is released last so both still have it.
+   *
+   * Idempotent. The host calls it on unload, on a config change and at
+   * shutdown, and those can overlap.
+   */
+  async dispose() {
+    if (this.currentHost === void 0) return;
+    for (const disposer of this.disposers.splice(0).reverse()) {
+      try {
+        await disposer();
+      } catch (error) {
+        this.currentHost.logger.warn("a plugin disposer failed", {
+          plugin: this.constructor.name,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    try {
+      await this.onUnload();
+    } finally {
+      this.currentHost = void 0;
+    }
+  }
+};
+
+// src/plugin.config.fields.ts
+import { z } from "zod";
+function parseMultiSelect(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((value) => typeof value === "string" && value.trim().length > 0).map((value) => value.trim());
+  } catch {
+    return [];
+  }
+}
+__name(parseMultiSelect, "parseMultiSelect");
+var ROW_ID_KEY = "$id";
+function rowSecretKey(fieldKey, rowId, columnKey) {
+  return `${fieldKey}/${rowId}/${columnKey}`;
+}
+__name(rowSecretKey, "rowSecretKey");
+function isRowSecretKey(key) {
+  return key.split("/").length === 3;
+}
+__name(isRowSecretKey, "isRowSecretKey");
+function parseRows(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.flatMap((entry) => {
+      if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return [];
+      const row = {};
+      for (const [key, value] of Object.entries(entry)) {
+        if (typeof value === "string" && value.trim().length > 0) row[key] = value.trim();
+      }
+      return Object.keys(row).length === 0 ? [] : [
+        row
+      ];
+    });
+  } catch {
+    return [];
+  }
+}
+__name(parseRows, "parseRows");
+var configFieldOptionSchema = z.object({
+  value: z.string(),
+  label: z.string()
+});
+var configFieldTypeSchema = z.enum([
+  "string",
+  "text",
+  "url",
+  "secret",
+  "number",
+  "boolean",
+  "select",
+  "multiselect",
+  "list",
+  "note"
+]);
+var configFieldUnitSchema = z.enum([
+  "bytes",
+  "fraction"
+]);
+var configFieldControlSchema = z.enum([
+  "slider",
+  "tags"
+]);
+var configFieldOptionSourceSchema = z.enum([
+  "station.newsCategories",
+  "station.newsFeeds",
+  "intl.timeZones",
+  "plugins.speech",
+  "plugins.llm",
+  "plugins.mixer",
+  "plugins.analysis",
+  "llm.models"
+]);
+var noSeparator = /* @__PURE__ */ __name((key) => !key.includes("/"), "noSeparator");
+var separatorMessage = 'a key may not contain "/"';
+var configFieldColumnSchema = z.object({
+  key: z.string().min(1).refine(noSeparator, separatorMessage),
+  label: z.string().min(1),
+  type: z.enum([
+    "string",
+    "url",
+    "select",
+    "secret"
+  ]),
+  required: z.boolean().optional(),
+  placeholder: z.string().optional(),
+  options: z.array(configFieldOptionSchema).optional(),
+  optionsFrom: configFieldOptionSourceSchema.optional(),
+  // Named here or dropped: `plugin.loader.ts` stores the zod OUTPUT of this schema as the
+  // manifest, and a `z.object` strips what it does not name. A column declaring a condition this
+  // schema had not been told about would lose it at load, in silence, and present as a console
+  // that ignores the declaration.
+  //
+  // No refinement tying the values to a target. The `.ck` contract mirroring this cannot express
+  // one, and a schema that refuses what the contract accepts is the drift the generated-output
+  // rule exists to prevent; values without a target are documented as ignored instead.
+  dependsOn: z.string().min(1).optional(),
+  dependsOnValues: z.array(z.string().min(1)).optional()
+});
+var configFieldSchema = z.object({
+  key: z.string().min(1).refine(noSeparator, separatorMessage),
+  label: z.string().min(1),
+  type: configFieldTypeSchema,
+  required: z.boolean().optional(),
+  default: z.union([
+    z.string(),
+    z.number(),
+    z.boolean()
+  ]).optional(),
+  unit: configFieldUnitSchema.optional(),
+  control: configFieldControlSchema.optional(),
+  step: z.number().optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  placeholder: z.string().optional(),
+  help: z.string().optional(),
+  options: z.array(configFieldOptionSchema).optional(),
+  optionsFrom: configFieldOptionSourceSchema.optional(),
+  columns: z.array(configFieldColumnSchema).optional(),
+  dependsOn: z.string().optional(),
+  rangeWith: z.string().optional()
+});
+
+// src/plugin.config.read.ts
+function configString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed2 = value.trim();
+  return trimmed2.length > 0 ? trimmed2 : void 0;
+}
+__name(configString, "configString");
+function configBaseUrl(value) {
+  return (configString(value) ?? "").replace(/\/+$/, "");
+}
+__name(configBaseUrl, "configBaseUrl");
+async function readRowSecret(host, fieldKey, row, columnKey) {
+  const rowId = row[ROW_ID_KEY];
+  if (rowId === void 0 || rowId.length === 0) return void 0;
+  return await host.secrets.get(rowSecretKey(fieldKey, rowId, columnKey));
+}
+__name(readRowSecret, "readRowSecret");
+
+// src/plugin.host.response.ts
+var BODY_SNIPPET_LENGTH = 120;
+var snippet = /* @__PURE__ */ __name((body) => {
+  const trimmed2 = body.trim();
+  if (trimmed2.length === 0) return "<empty body>";
+  return trimmed2.length <= BODY_SNIPPET_LENGTH ? trimmed2 : `${trimmed2.slice(0, BODY_SNIPPET_LENGTH)}\u2026`;
+}, "snippet");
+async function jsonBody(response) {
+  const text2 = await response.text();
+  try {
+    return JSON.parse(text2);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`expected JSON from ${response.url} (HTTP ${response.status}) but got ${snippet(text2)}: ${reason}`, {
+      cause: error
+    });
+  }
+}
+__name(jsonBody, "jsonBody");
+async function tryJsonBody(response) {
+  const text2 = await response.text();
+  try {
+    return JSON.parse(text2);
+  } catch {
+    return void 0;
+  }
+}
+__name(tryJsonBody, "tryJsonBody");
+
+// src/plugin.manifest.ts
+import { z as z3 } from "zod";
+
+// src/plugin.permissions.ts
+import { z as z2 } from "zod";
+var pacingShape = {
+  ratePerSecond: z2.number().positive().finite().optional(),
+  bucket: z2.string().min(1).optional()
+};
+var networkPermissionSchema = z2.union([
+  z2.string().min(1),
+  z2.object({
+    host: z2.string().min(1),
+    ...pacingShape
+  }),
+  z2.object({
+    fromConfig: z2.string().min(1),
+    ...pacingShape
+  })
+]);
+var grantRequestSchema = z2.object({
+  capability: z2.string().min(1),
+  // Non-empty for the reason the field exists: an operator deciding on a
+  // capability id with no sentence beside it is being asked a question they
+  // cannot answer.
+  reason: z2.string().min(1),
+  ...pacingShape
+});
+var pluginPermissionsSchema = z2.object({
+  network: z2.array(networkPermissionSchema),
+  storage: z2.boolean(),
+  oauth: z2.boolean(),
+  trackFetcher: z2.boolean().optional(),
+  grants: z2.array(grantRequestSchema).optional()
+});
+
+// src/plugin.manifest.ts
+var PLUGIN_CAPABILITY_CATALOG = "catalog";
+var PLUGIN_CAPABILITY_STREAM = "stream";
+var PLUGIN_CAPABILITY_STEER = "steer";
+var PLUGIN_CAPABILITY_OAUTH = "oauth";
+var PLUGIN_CAPABILITY_ENRICHMENT = "enrichment";
+var PLUGIN_CAPABILITY_SPEECH = "speech";
+var PLUGIN_CAPABILITY_LLM = "llm";
+var PLUGIN_CAPABILITY_ANALYSIS = "analysis";
+var PLUGIN_CAPABILITY_MIXER = "mixer";
+var PLUGIN_CAPABILITY_CHARTS = "charts";
+var PLUGIN_CAPABILITY_NEWS = "news";
+var PLUGIN_CAPABILITY_SIMILARITY = "similarity";
+var PLUGIN_CAPABILITY_SEARCH = "search";
+var PLUGIN_CAPABILITY_WEATHER = "weather";
+var PLUGIN_CAPABILITY_SCROBBLE = "scrobble";
+var KNOWN_PLUGIN_CAPABILITIES = [
+  PLUGIN_CAPABILITY_CATALOG,
+  PLUGIN_CAPABILITY_STREAM,
+  PLUGIN_CAPABILITY_STEER,
+  PLUGIN_CAPABILITY_OAUTH,
+  PLUGIN_CAPABILITY_ENRICHMENT,
+  PLUGIN_CAPABILITY_SPEECH,
+  PLUGIN_CAPABILITY_LLM,
+  PLUGIN_CAPABILITY_ANALYSIS,
+  PLUGIN_CAPABILITY_MIXER,
+  PLUGIN_CAPABILITY_CHARTS,
+  PLUGIN_CAPABILITY_NEWS,
+  PLUGIN_CAPABILITY_SIMILARITY,
+  PLUGIN_CAPABILITY_SEARCH,
+  PLUGIN_CAPABILITY_WEATHER,
+  PLUGIN_CAPABILITY_SCROBBLE
+];
+function isZodSchema(value) {
+  if (value instanceof z3.ZodType) return true;
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.parse === "function" && typeof candidate.safeParse === "function";
+}
+__name(isZodSchema, "isZodSchema");
+var PLUGIN_ID_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/;
+var pluginManifestSchema = z3.object({
+  id: z3.string().regex(PLUGIN_ID_PATTERN, 'plugin id must be reverse-DNS, e.g. "deadair.spotify"'),
+  name: z3.string().min(1),
+  version: z3.string().min(1),
+  capabilities: z3.array(z3.string().min(1)),
+  apiVersion: z3.string().min(1),
+  description: z3.string().optional(),
+  homepage: z3.string().optional(),
+  icon: z3.string().optional(),
+  permissions: pluginPermissionsSchema,
+  configFields: z3.array(configFieldSchema),
+  configSchema: z3.custom(isZodSchema, {
+    message: "configSchema must be a zod schema"
+  })
+});
+export {
+  ANALYSIS_SCHEMA_VERSION,
+  ARTICLE_MAX_CHARS,
+  BOUNDARY_LIVE_OBJECT_TYPES,
+  BOUNDARY_METHOD_TYPES,
+  ENRICHMENT_MATCH_KEY_ARTIST_TITLE,
+  ENRICHMENT_MATCH_KEY_ISRC,
+  FEED_SUMMARY_MAX_CHARS,
+  HOST_FETCH_METHODS,
+  JSON_SAFE_PAYLOAD_TYPES,
+  KNOWN_ENRICHMENT_MATCH_KEYS,
+  KNOWN_PLUGIN_CAPABILITIES,
+  PLUGIN_API_VERSION,
+  PLUGIN_CAPABILITY_ANALYSIS,
+  PLUGIN_CAPABILITY_CATALOG,
+  PLUGIN_CAPABILITY_CHARTS,
+  PLUGIN_CAPABILITY_ENRICHMENT,
+  PLUGIN_CAPABILITY_LLM,
+  PLUGIN_CAPABILITY_MIXER,
+  PLUGIN_CAPABILITY_NEWS,
+  PLUGIN_CAPABILITY_OAUTH,
+  PLUGIN_CAPABILITY_SCROBBLE,
+  PLUGIN_CAPABILITY_SEARCH,
+  PLUGIN_CAPABILITY_SIMILARITY,
+  PLUGIN_CAPABILITY_SPEECH,
+  PLUGIN_CAPABILITY_STEER,
+  PLUGIN_CAPABILITY_STREAM,
+  PLUGIN_CAPABILITY_WEATHER,
+  PLUGIN_ERROR_CODES,
+  Plugin,
+  PluginError,
+  ROW_ID_KEY,
+  SPEECH_CUES,
+  baseForm,
+  collectGeneration,
+  configBaseUrl,
+  configFieldColumnSchema,
+  configFieldControlSchema,
+  configFieldOptionSchema,
+  configFieldOptionSourceSchema,
+  configFieldSchema,
+  configFieldTypeSchema,
+  configFieldUnitSchema,
+  configString,
+  cuesIn,
+  decodeEntities,
+  definePlugin,
+  errorText,
+  extractArticle,
+  fetchArticle,
+  fetchFeed,
+  firstSentence,
+  grantRequestSchema,
+  headersToRecord,
+  hostFetchMethod,
+  isPluginError,
+  isResourceScopedCode,
+  isRowSecretKey,
+  isZodSchema,
+  jsonBody,
+  networkPermissionSchema,
+  normalize,
+  parseFeed,
+  parseMultiSelect,
+  parseRows,
+  plainText,
+  pluginCodeForStatus,
+  pluginManifestSchema,
+  pluginPermissionsSchema,
+  readRowSecret,
+  retryAfterMs,
+  rowSecretKey,
+  sentencesWithin,
+  toPluginError,
+  truncateSentences,
+  truncateUpstreamMessage,
+  truncateWords,
+  tryJsonBody,
+  upstreamDetail,
+  upstreamField,
+  withoutCues
+};
+//# sourceMappingURL=index.js.map