@deadair/plugin-sdk 0.2.0

package/dist/capabilities/search.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The `search` kind. A search plugin answers an OPEN question by asking a search
+ * engine, and hands back what the engine said.
+ *
+ * ## This is the open web, not the library
+ *
+ * Nothing here is about records. Looking for something to play is
+ * `music.provider.searchTracks`, which answers with tracks that carry provider
+ * ids the pick path can resolve; every result here is a page, and a page cannot
+ * be scheduled. The two are different questions with different answers, and the
+ * host keeps them apart so a model steered by one is never handed the other.
+ *
+ * ## Why this is not `news`
+ *
+ * A news plugin serves a MENU an operator assembled: feeds somebody chose, with
+ * ids, categories and a de-duplication contract, answering "what happened". This
+ * answers "what does the web say about X" — the caller supplies the subject, the
+ * plugin has no idea what will come back, and there is nothing stable to
+ * de-duplicate against because no two calls ask the same question.
+ *
+ * ## It reports what the engine said, and it does not summarise
+ *
+ * A {@link SearchResult.snippet} is the engine's own text, trimmed of markup and
+ * otherwise untouched. Several engines will also sell a synthesized ANSWER —
+ * Tavily's `answer`, SearXNG's infobox — and this capability deliberately has
+ * nowhere to put one. That paragraph is somebody else's model paraphrasing pages
+ * this station never sees, so nothing can check it against a source, and a claim
+ * that cannot be checked is one the station must not broadcast. The same
+ * boundary `capabilities/enrichment.ts` keeps with `SourceDocument`: a plugin
+ * fetches and the host thinks.
+ *
+ * A plugin that wants to contribute PROSE the host can extract claims from
+ * declares `enrichment` as well and returns documents there, where the fact
+ * store's provenance and quote checking already live.
+ *
+ * ## Nothing here airs
+ *
+ * A result is words on a page. Whether any of it is spoken is settled by a break
+ * writer on a station that is on air, and this capability has no way to reach one.
+ *
+ * Every shape here is JSON-safe.
+ */
+/**
+ * How fresh a result has to be.
+ *
+ * Coarse on purpose, because that is how every engine models it: Brave takes
+ * `pd|pw|pm|py`, SearXNG takes `day|week|month|year`, and an exact window is not
+ * on offer anywhere. A plugin whose engine cannot filter by age ignores it
+ * rather than filtering the page itself, since a result's date is frequently the
+ * one field an engine gets wrong.
+ */
+export type SearchRecency = 'day' | 'week' | 'month' | 'year';
+/** What a search source is asked. */
+export interface SearchQuery {
+    /** The words to search for, as somebody would type them. */
+    query: string;
+    /** How many results to return. A plugin may return fewer; it must not return more. */
+    limit: number;
+    /** Only results this recent, when the engine can say. Absent for anything, whatever its age. */
+    recency?: SearchRecency;
+    /** ISO 639-1, when the caller has an opinion about what language the answer should be in. */
+    language?: string;
+    /**
+     * Only pages on these hostnames, when the caller is asking a narrow question.
+     *
+     * Every engine expresses this and none of them agree on how: `site:` in the
+     * query for the ones that take operators, a list parameter for the ones that
+     * do not. A plugin that cannot ask its engine at all filters what came back
+     * rather than ignoring this, because a caller that named its sites is
+     * usually about to do something with the pages that only holds for those
+     * sites — which is what the enrichment half of `plugins/websearch` does with
+     * the operator's own allowlist.
+     *
+     * Bare hostnames, no scheme and no path. Best-effort in the sense that an
+     * engine may still find nothing on them; never in the sense that something
+     * else may come back.
+     */
+    sites?: string[];
+}
+/** One hit. */
+export interface SearchResult {
+    /** The page's title, as the engine gave it. */
+    title: string;
+    /**
+     * The engine's own extract, as PLAIN TEXT.
+     *
+     * Never markup. Search APIs are the worst offenders here: Brave highlights
+     * query terms with `<strong>` unless told not to, and descriptions carry
+     * HTML entities either way. Both end up in a model's context and possibly in
+     * a speaking voice, so `html.text.ts` is what a plugin runs them through.
+     */
+    snippet: string;
+    /** Where the page is. Kept so a caller can cite it, read it, or check it against an allowlist. */
+    url: string;
+    /**
+     * Who published it, in the fewest words a presenter could say out loud.
+     *
+     * The engine's own profile name where it has one, and the hostname
+     * otherwise. It exists because attribution is the only part of a result a
+     * station can broadcast: a URL read aloud is the least useful sentence radio
+     * has ever carried, and "according to the Guardian" is a real one.
+     */
+    site?: string;
+    /** ISO-8601. Never a `Date`, and absent whenever the engine did not say — which is most results. */
+    publishedAt?: string;
+}
+/**
+ * Implemented by a `search` plugin.
+ */
+export interface SearchProvider {
+    /**
+     * Run the query, best first.
+     *
+     * An empty array is an ordinary answer and not a failure: an unconfigured
+     * plugin, an engine that is down, a rate limit and a query nothing matches
+     * are one outcome to every caller, and the difference belongs in the
+     * plugin's own log. Throw only for something the operator has to fix, since
+     * the host turns a throw into a line an operator reads.
+     */
+    search(query: SearchQuery): Promise<SearchResult[]>;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/capabilities/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9D,qCAAqC;AACrC,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAe;AACf,MAAM,WAAW,YAAY;IACzB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACvD"}

package/dist/capabilities/similarity.d.ts

@@ -0,0 +1,101 @@
+import type { ArtistRef } from './enrichment.js';
+/**
+ * The `similarity` kind. A similarity plugin answers "who else sounds like this",
+ * and optionally "what should I play by them".
+ *
+ * ## Why this is not part of `enrichment`
+ *
+ * Enrichment describes something the catalog HOLDS: the host walks its own rows,
+ * stores an answer per provider against the row, and trusts it for ninety days.
+ * Every part of that machinery is keyed to a catalog row.
+ *
+ * The artists worth asking about here are precisely the ones the catalog does not
+ * hold. A station that only ever hears about acts already in its library is
+ * exactly the bubble this exists to break — so the question cannot be keyed to a
+ * row, and the answer is not a fact to store against one. It is a list of NAMES
+ * that feeds the same pick path a chart does, where the rules already decide what
+ * may actually air.
+ *
+ * ## Names in, names out
+ *
+ * Nothing here carries a track id, a provider id or a URL, and that is what keeps
+ * a similarity plugin from being able to put a record on air. It suggests; the
+ * host looks the suggestion up, ingests it if a provider has it, and then judges
+ * it like anything else.
+ *
+ * Every shape here is JSON-safe.
+ */
+/**
+ * An artist a source says resembles the one that was asked about.
+ *
+ * `mbid` and `providerRef` mirror {@link ArtistRef}'s: the first crosses
+ * providers, the second is this plugin's own id handed back so a follow-up is a
+ * lookup rather than another search. Neither is promised — the name is the only
+ * field anything downstream requires, because the name is what the pick path
+ * matches on.
+ */
+export interface SimilarArtist {
+    name: string;
+    /** MusicBrainz artist id, when the source knows one. */
+    mbid?: string;
+    /** This plugin's own id for the artist, for a later {@link SimilarityProvider.artistTopTracks}. */
+    providerRef?: string;
+    /**
+     * How alike, from 0 to 1, where the source scores it.
+     *
+     * A HINT for ordering and nothing else. Sources score on wildly different
+     * bases — co-listening, tags, editorial — so the host orders within one
+     * source's answer and never compares two sources' numbers as if they meant
+     * the same thing.
+     */
+    match?: number;
+}
+/**
+ * A record by an artist, offered as something to play.
+ *
+ * The same shape a chart entry reduces to, and for the same reason: it is a
+ * title and a lead artist, which is what a pick is.
+ */
+export interface ArtistTrack {
+    title: string;
+    /**
+     * The LEAD artist, never a credit line.
+     *
+     * The same correctness rule the chart capability carries: everything
+     * downstream matches a pick on the lead artist alone, so a joined credit is
+     * a record that is named correctly and then dropped as one nothing can find.
+     */
+    artist: string;
+    album?: string;
+    year?: number;
+}
+/**
+ * Implemented by a `similarity` plugin.
+ */
+export interface SimilarityProvider {
+    /**
+     * Artists that resemble this one, best first.
+     *
+     * An empty array is an ordinary answer and not a failure: an unconfigured
+     * plugin, an artist the source has never heard of, and one nothing resembles
+     * are all "nothing to add".
+     *
+     * `limit` is a ceiling on what to return. Returning fewer is fine; returning
+     * more wastes an upstream call, since the host trims.
+     */
+    similarArtists(ref: ArtistRef, limit: number): Promise<SimilarArtist[]>;
+    /**
+     * What to play by an artist, best first.
+     *
+     * Optional, the way `enrichArtist` is on the enrichment capability. A source
+     * that can only say who sounds alike is a legitimate plugin — but note what
+     * absent costs: the host has a name and no way to turn it into a record, so
+     * a plugin without this can inform a DJ and cannot programme an hour.
+     *
+     * The artist here is one the caller chose, which is usually one this plugin
+     * itself named. When it carries a `providerRef` this plugin put there, that
+     * is its own id coming back.
+     */
+    artistTopTracks?(ref: ArtistRef, limit: number): Promise<ArtistTrack[]>;
+}
+//# sourceMappingURL=similarity.d.ts.map

package/dist/capabilities/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../src/capabilities/similarity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;;;;;OASG;IACH,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAExE;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC3E"}

package/dist/capabilities/speech.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The `speech` capability. A speech plugin takes a line of text and answers
+ * with audio: the station saying its own name, reading a back-announce, or
+ * delivering a whole talk break.
+ *
+ * ## The audio comes back as a stream, not as a value
+ *
+ * {@link SpeechPluginInstance.speak} returns a stream rather than bytes, and
+ * the usual implementation is to hand back the `host.fetch` body of the engine
+ * call unchanged. So the audio is never held whole anywhere, and a long script
+ * costs a chunk of memory rather than a file of it.
+ *
+ * Cancellation is the host's `cancel()` on that stream, and forwarding a
+ * `host.fetch` body propagates it to the socket for you. There is nothing to
+ * implement.
+ *
+ * ## A voice is a name the station chose, not one your engine knows
+ *
+ * {@link SpeechRequest.voice} is an opaque id from the station's side of the
+ * fence — `host`, `newsreader` — and mapping it to whatever your engine actually
+ * takes is your job, out of your own config. The host never reads it, never
+ * validates it, and never stores anything engine-specific.
+ *
+ * The indirection is the point, and it was paid for once already: it is what
+ * lets the same station voice be a named preset on one engine and a cloned
+ * reference clip on another, so changing engine does not rewrite every persona.
+ * Keep engine-specific tuning (an expressiveness dial, a similarity weight)
+ * inside your own config where it belongs, rather than asking the host to carry
+ * knobs only you understand.
+ *
+ * Every shape here is JSON-safe.
+ */
+import type { PluginLifecycle } from '../plugin.lifecycle.js';
+/**
+ * The things a presenter DOES that are not words, as the station names them.
+ *
+ * A cue rides inside {@link SpeechRequest.text} rather than beside it, written
+ * `[laugh]`, which is why nothing in this interface carries one. That is not a
+ * shortcut: a laugh happens at a place in a sentence, and a field would have to
+ * invent a way to say where.
+ *
+ * The vocabulary is the STATION's and mapping it is yours, exactly as for
+ * {@link SpeechVoice}. A laugh is something a presenter does; whether your engine
+ * spells it `[laugh]`, `<laugh>` or not at all is engine business, and the host
+ * never learns which.
+ *
+ * ## Eight, and the second four are not for the presenter
+ *
+ * This was four, and its stated reason for stopping there was that "a cough or a
+ * sniff reads as illness rather than as delivery". That is right about somebody
+ * being paid to talk and exactly wrong about somebody on the end of a telephone,
+ * where the throat-clear IS the realism — so the vocabulary is wider now and WHO
+ * may use which is the host's business rather than this list's.
+ *
+ * The host keeps the first four. A caller in a production may use all eight. Both
+ * sets live app-side, because they are permissions rather than capabilities, and
+ * a plugin has no way to know which of its speakers is which.
+ *
+ * **Widening this list without narrowing the offer is how the presenter starts
+ * coughing.** Whatever reads a script back has to be told which of these were
+ * actually on offer to the person who wrote it, rather than reaching for the whole
+ * vocabulary.
+ *
+ * Still chosen rather than copied from an engine: `shush` is one this list does
+ * not take, because shushing is aimed AT somebody in the room. That is a piece of
+ * business rather than a way of delivering a line.
+ *
+ * **Answer {@link SpeechPluginInstance.listCues} honestly and the rest is free.**
+ * The host strips every cue you do not claim before it calls {@link
+ * SpeechPluginInstance.speak}, so a plugin that implements nothing here never sees
+ * one, and the failure where an engine READS the word "laugh" out loud cannot
+ * happen. Claiming one you cannot perform is the only way to break that.
+ */
+export declare const SPEECH_CUES: readonly ["laugh", "chuckle", "sigh", "gasp", "cough", "clear throat", "sniff", "groan"];
+/** One of {@link SPEECH_CUES}. */
+export type SpeechCue = (typeof SPEECH_CUES)[number];
+/** Every cue written into a script, in the order they appear, with repeats. */
+export declare function cuesIn(text: string): SpeechCue[];
+/**
+ * The same text with cues removed, or with only some of them kept.
+ *
+ * `keep` is the set to LEAVE, so the default of none is "take them all out" — the
+ * safe direction, and the one an engine that has never heard of a cue wants. A
+ * removal closes the space it leaves behind, because `word [laugh] word` would
+ * otherwise render with a double space that {@link SPEECH_CUES}' own consumers
+ * would have to know to tidy.
+ *
+ * Only the four are touched. Anything else in brackets is somebody else's problem
+ * and stays exactly as it arrived: this is not a bracket stripper.
+ */
+export declare function withoutCues(text: string, keep?: Iterable<SpeechCue>): string;
+/** One thing to say. */
+export interface SpeechRequest {
+    /**
+     * The words, already final. Nothing downstream rewrites them, so any
+     * pronunciation fixing your engine needs is yours to apply.
+     */
+    text: string;
+    /**
+     * Which station voice to use, or absent for this plugin's default.
+     *
+     * Opaque, and a name the operator chose. An id you have no mapping for
+     * should fall back to your default rather than fail: a missing voice is
+     * worth a `logger.warn` and a rendered line, not a silent station.
+     */
+    voice?: string;
+    /**
+     * The audio format the caller would prefer, as a bare extension (`mp3`).
+     *
+     * A hint, and the weakest thing in this interface: answer with whatever you
+     * actually produced in {@link SpeechHandle.mime} and the host will believe
+     * that instead. Ignore it entirely if your engine emits one format.
+     */
+    format?: string;
+}
+/** The audio for one {@link SpeechPluginInstance.speak}, and what it is. */
+export interface SpeechHandle {
+    /**
+     * What the bytes ARE, as a media type (`audio/mpeg`).
+     *
+     * Load-bearing rather than decoration: it is what the host stores the audio
+     * under and what it later serves, and both consumers of station audio (a
+     * browser's `<audio>`, which does not sniff, and the playout engine, which
+     * picks its decoder from the content type) go by that header rather than by
+     * the bytes. A wav announced as `audio/mpeg` fails as silence rather than
+     * as an error anybody sees.
+     */
+    mime: string;
+    /**
+     * The audio.
+     *
+     * The host reads it to the end or cancels it, and either one releases
+     * whatever is underneath. Usually a `host.fetch` body forwarded unchanged,
+     * which is what makes that true for free.
+     */
+    audio: ReadableStream<Uint8Array>;
+}
+/** One voice this plugin can be asked for. */
+export interface SpeechVoice {
+    /** The id to pass back as {@link SpeechRequest.voice}. */
+    id: string;
+    /** What the console calls it. */
+    label: string;
+    /** Anything worth knowing when choosing between them: an accent, a register. */
+    description?: string;
+    /**
+     * An opaque token that changes when what this voice SOUNDS LIKE changes.
+     *
+     * The host does not interpret it, parse it, store it or show it. It uses it
+     * for one thing: keying the cached preview at `GET /voices/{id}/sample`, so
+     * that remapping `host` from one engine voice to another — or nudging its
+     * speed, or swapping its reference clip — mints a new key and the next
+     * preview renders instead of playing the old voice back.
+     *
+     * That was already the claim `VoiceSampleStore` made in its own doc comment
+     * and it was not true: the key held the STATION voice id, which is exactly
+     * the part that does not change when an operator edits the mapping under it.
+     * The fence is intact because this stays opaque — whatever string identifies
+     * a rendering to you is the right value, and `engineVoice@speed` is a fine
+     * one.
+     *
+     * Absent is normal. A plugin that omits it keys previews as it always did,
+     * which is correct for one whose voices cannot be reconfigured.
+     */
+    spec?: string;
+}
+/** A plugin that can speak. */
+export interface SpeechPluginInstance extends PluginLifecycle {
+    /**
+     * Start turning `request.text` into audio.
+     *
+     * May return before any audio exists, because the handle carries a stream
+     * and not the bytes, so a slow engine shows up as a slow first chunk rather
+     * than as a slow `speak`.
+     *
+     * @throws {PluginError} `config` when the plugin is not set up enough to try
+     *   (no server address), `upstream` when the engine refused or answered with
+     *   something that is not audio, `timeout` when it did not answer at all.
+     */
+    speak(request: SpeechRequest): Promise<SpeechHandle>;
+    /**
+     * The voices this plugin can be asked for, for a console that has to draw a
+     * list.
+     *
+     * Optional, because a plugin with exactly one voice is a legitimate thing to
+     * be and should not have to describe it. Absent is normal, not broken.
+     */
+    listVoices?(): Promise<SpeechVoice[]>;
+    /**
+     * Which of {@link SPEECH_CUES} this plugin can perform RIGHT NOW.
+     *
+     * Optional, and absent means none: an engine that only reads words is the
+     * ordinary case and should not have to say so. That default is what makes this
+     * safe to add — the host strips what you do not claim, so silence costs a
+     * plugin nothing and risks nothing.
+     *
+     * **Answer from what the engine currently IS, not from what this plugin was
+     * built against.** On the engine this was written for, cues belong to the
+     * loaded MODEL rather than to the server, so swapping the model takes them away
+     * with no plugin change involved — which is exactly the case a manifest flag
+     * would get wrong, and it would get it wrong by having the station perform to
+     * an engine that reads the word out.
+     *
+     * Called on the path that writes a break as well as the one that speaks it, so
+     * keep it cheap and answer empty rather than throwing when the engine cannot be
+     * reached: a station that cannot ask should write a script with no cues in it,
+     * not fail to write one.
+     */
+    listCues?(): Promise<readonly SpeechCue[]>;
+}
+//# sourceMappingURL=speech.d.ts.map

package/dist/capabilities/speech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.d.ts","sourceRoot":"","sources":["../../src/capabilities/speech.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,WAAW,0FAA2F,CAAC;AAEpH,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAEhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,CAAC,SAAS,CAAM,GAAG,MAAM,CAQhF;AAYD,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IACzB;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IACxB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IACzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;CAC9C"}

package/dist/capabilities/weather.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The `weather` kind. A weather plugin answers "what is it like outside", for
+ * one place, as numbers.
+ *
+ * ## Why this is not `news`, and not `search`
+ *
+ * All three answer about the world rather than about records, and they are asked
+ * different questions. News serves a MENU an operator assembled and answers
+ * "what happened", with a de-duplication contract because the same entry comes
+ * back on every poll. Search takes words the caller made up and answers "what
+ * does the web say about that", with nothing stable to de-duplicate against.
+ * This is asked about one PLACE and answers with measurements — a temperature is
+ * not a headline, and the station wants to do arithmetic on it rather than read
+ * it out verbatim.
+ *
+ * ## The plugin resolves the place, and the host never geocodes
+ *
+ * {@link WeatherQuery.place} is a name somebody typed, and turning it into
+ * coordinates is exactly the per-service quirk this boundary exists to absorb:
+ * one service ships a geocoder, one takes coordinates only, one wants its own
+ * city ids. A host that geocoded would have to pick one of those services to
+ * geocode WITH, which is the shape of dependency a capability is supposed to
+ * remove.
+ *
+ * {@link WeatherReading.place} comes back as the SERVICE resolved it, because a
+ * DJ has to be able to say a real place name rather than whatever was typed into
+ * a settings box.
+ *
+ * ## Everything is metric
+ *
+ * Temperatures in Celsius, wind in km/h, and no unit field anywhere. What a
+ * station SAYS is a station's own decision — a British station says Celsius
+ * whichever service it reads — and it is settled where the words are made,
+ * beside every other decision about how this station talks. A plugin converting
+ * would mean the units on the wire depended on which plugin was installed, which
+ * is the one thing a capability must not let happen.
+ *
+ * This is `ConfigField.unit`'s rule one layer down: the value on the wire is
+ * always the declared unit, and nothing downstream learns that the presentation
+ * converts.
+ *
+ * ## A condition is a closed vocabulary
+ *
+ * {@link WeatherCondition} is short and fixed. WMO code 73, an icon string of
+ * `snow`, and a numeric condition id are three spellings of the same weather,
+ * and mapping them is the plugin's job for {@link WeatherQuery.place}'s reason.
+ * The service's own word survives beside it as
+ * {@link WeatherConditions.description}, unread by anything that speaks
+ * deterministically and available to a model that wants a phrase somebody wrote.
+ *
+ * ## Nothing here airs
+ *
+ * A reading is a number. Whether any of it is spoken is settled by a break
+ * writer on a station that is on air, and this capability has no way to reach
+ * one.
+ *
+ * Every shape here is JSON-safe.
+ */
+/**
+ * What the sky is doing, in the fewest words that are still distinguishable.
+ *
+ * Ten arms, chosen so a station can say something true about each one without a
+ * caveat, and deliberately not a scale: an intensity ("heavy rain") belongs on
+ * the numbers, where a caller can decide for itself what counts as heavy. Every
+ * service's own scheme collapses onto this and the plugin is what does the
+ * collapsing.
+ */
+export type WeatherCondition = 'clear' | 'cloudy' | 'overcast' | 'fog' | 'drizzle' | 'rain' | 'snow' | 'sleet' | 'thunderstorm' | 'hail';
+/** What a weather source is asked. */
+export interface WeatherQuery {
+    /**
+     * The place, as somebody wrote it: `Atlanta`, `Chipping Norton, Oxfordshire`.
+     *
+     * Resolved by the plugin. See the note on this file about why the host does
+     * not do it, and {@link WeatherReading.place} for what comes back.
+     */
+    place: string;
+    /**
+     * How many days of forecast to include beyond the current conditions.
+     *
+     * `0` or absent asks for now alone, which is the common call. A count rather
+     * than named horizons (`today`, `tomorrow`, `week`) because those are words
+     * for a person and this is a number for a service — and because the words
+     * differ per caller: a break writer's "the weekend" and a model's "this week"
+     * are the same request with different arithmetic in front of it.
+     *
+     * A plugin CAPS this at whatever its service will give and answers with what
+     * it got, rather than refusing. Asking for more days than exist is a caller
+     * being optimistic, not a caller being wrong.
+     */
+    days?: number;
+}
+/**
+ * What it is like, at one moment or across one day.
+ *
+ * Every measurement is optional, and that is a fact about the services rather
+ * than caution: they report different subsets, a forecast day carries figures an
+ * observation does not, and a station that must ask whether it HAS the humidity
+ * before mentioning it is a station that never says something it does not know.
+ * A zero would be a lie in exactly the cases that matter.
+ */
+export interface WeatherConditions {
+    condition: WeatherCondition;
+    /**
+     * The service's own words for it: `light drizzle`, `partly cloudy`.
+     *
+     * Raw material for a model, never read verbatim by anything deterministic —
+     * the same standing `NewsItem.summary` has. Plain text, and absent whenever
+     * the service offers nothing better than the code that became
+     * {@link condition}.
+     */
+    description?: string;
+    /** Degrees Celsius. See the note on this file: everything here is metric. */
+    temperatureC?: number;
+    /** Degrees Celsius, as it feels with the wind and the humidity, when the service computes one. */
+    feelsLikeC?: number;
+    /** Kilometres per hour. */
+    windKph?: number;
+    /** Relative humidity, as a percentage between 0 and 100. */
+    humidity?: number;
+    /** The chance of precipitation, as a percentage between 0 and 100. Rare on an observation. */
+    precipitationChance?: number;
+}
+/** One day of the forecast. */
+export interface WeatherDay extends WeatherConditions {
+    /**
+     * The calendar day AT THE PLACE, as `YYYY-MM-DD`. Never a `Date`.
+     *
+     * At the place rather than at the server, because that is the only reading of
+     * it that makes "tomorrow" mean what a listener thinks it means. A station in
+     * one timezone reporting a town in another is an ordinary thing to ask for.
+     */
+    date: string;
+    highC?: number;
+    lowC?: number;
+    /** ISO-8601. Never a `Date`. */
+    sunrise?: string;
+    /** ISO-8601. Never a `Date`. */
+    sunset?: string;
+}
+/** What one place is like. */
+export interface WeatherReading {
+    /**
+     * The place as the SERVICE resolved it, which is not what was asked for.
+     *
+     * Kept because it is the part a presenter says out loud, and because it is
+     * the only evidence anybody has that the right town was found: a station
+     * announcing the weather in Birmingham, Alabama to an audience in Birmingham
+     * is a failure nothing else here can detect.
+     */
+    place: string;
+    /**
+     * When the observation was made, as an ISO-8601 string. Never a `Date`.
+     *
+     * Not when it was fetched. A plugin serving a cached reading reports the age
+     * of the READING, which is what lets a caller decide a forecast is too old to
+     * broadcast — a decision no plugin is in a position to make, since only the
+     * caller knows whether anybody is listening.
+     */
+    observedAt: string;
+    /** What it is like right now. */
+    current: WeatherConditions;
+    /**
+     * Today first, then forward.
+     *
+     * Absent or empty when {@link WeatherQuery.days} asked for none, and when the
+     * service has no forecast to give. Those are the same answer to a caller, and
+     * the difference belongs in the plugin's own log.
+     */
+    days?: WeatherDay[];
+}
+/**
+ * Implemented by a `weather` plugin.
+ */
+export interface WeatherProvider {
+    /**
+     * What it is like there.
+     *
+     * `undefined` is an ordinary answer and not a failure: an unconfigured
+     * plugin, a place the service could not resolve, and a service that is down
+     * are one outcome to every caller, which is {@link SearchProvider.search}'s
+     * empty array wearing the shape this capability has. Throw only for something
+     * the operator has to go and fix, since the host turns a throw into a line an
+     * operator reads.
+     *
+     * A place that resolved to somewhere unexpected is NOT one of those cases and
+     * must be answered rather than swallowed — {@link WeatherReading.place} is
+     * how that becomes visible.
+     */
+    getWeather(query: WeatherQuery): Promise<WeatherReading | undefined>;
+}
+//# sourceMappingURL=weather.d.ts.map

package/dist/capabilities/weather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weather.d.ts","sourceRoot":"","sources":["../../src/capabilities/weather.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,CAAC;AAEzI,sCAAsC;AACtC,MAAM,WAAW,YAAY;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAW,SAAQ,iBAAiB;IACjD;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC3B;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CACxE"}

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export {
+  __name
+};
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}