@deadair/plugin-sdk 0.2.0

package/dist/define.plugin.d.ts

@@ -0,0 +1,56 @@
+import type { ChartsProvider } from './capabilities/charts.js';
+import type { EnrichmentProvider } from './capabilities/enrichment.js';
+import type { MusicProviderCatalog, MusicProviderOAuth, MusicProviderSteer, MusicProviderStream } from './capabilities/music.provider.js';
+import type { NewsProvider } from './capabilities/news.js';
+import type { ScrobbleProvider } from './capabilities/scrobble.js';
+import type { SearchProvider } from './capabilities/search.js';
+import type { SimilarityProvider } from './capabilities/similarity.js';
+import type { WeatherProvider } from './capabilities/weather.js';
+import type { PluginManifest } from './plugin.manifest.js';
+import type { PluginLifecycle } from './plugin.lifecycle.js';
+/**
+ * A plugin instance: the lifecycle, plus whatever capability interfaces the
+ * plugin declared in `manifest.capabilities`.
+ */
+export type PluginInstance = PluginLifecycle;
+/**
+ * Builds a fresh plugin instance. The host calls this once per configured
+ * installation, then calls `init(host)` on the result. Do no I/O here: keep
+ * the constructor cheap and put setup in `init`.
+ */
+export type PluginFactory<TInstance extends PluginInstance = PluginInstance> = () => TInstance;
+/** What a plugin package default-exports. */
+export interface DeadairPlugin<TInstance extends PluginInstance = PluginInstance> {
+    manifest: PluginManifest;
+    factory: PluginFactory<TInstance>;
+}
+/**
+ * Instance shape for a `music-provider` plugin. Every capability method is
+ * optional: implement the subset you declared in `manifest.capabilities`.
+ */
+export type MusicProviderPluginInstance = PluginLifecycle & Partial<MusicProviderCatalog> & Partial<MusicProviderStream> & Partial<MusicProviderSteer> & Partial<MusicProviderOAuth>;
+/** Instance shape for an `enrichment` plugin. */
+export type EnrichmentPluginInstance = PluginLifecycle & EnrichmentProvider;
+/** Instance shape for a `charts` plugin. */
+export type ChartsPluginInstance = PluginLifecycle & ChartsProvider;
+/** Instance shape for a `news` plugin. */
+export type NewsPluginInstance = PluginLifecycle & NewsProvider;
+/** Instance shape for a `similarity` plugin. */
+export type SimilarityPluginInstance = PluginLifecycle & SimilarityProvider;
+/** Instance shape for a `search` plugin. */
+export type SearchPluginInstance = PluginLifecycle & SearchProvider;
+/** Instance shape for a `weather` plugin. */
+export type WeatherPluginInstance = PluginLifecycle & WeatherProvider;
+/** Instance shape for a `scrobble` plugin. */
+export type ScrobblePluginInstance = PluginLifecycle & ScrobbleProvider;
+/**
+ * Pairs a manifest with its factory and returns the object a plugin package
+ * default-exports. Purely a typing helper: it does no validation, because the
+ * host validates the manifest with `pluginManifestSchema` at load time.
+ *
+ * ```ts
+ * export default definePlugin(manifest, () => new MyPlugin());
+ * ```
+ */
+export declare function definePlugin<TInstance extends PluginInstance>(manifest: PluginManifest, factory: PluginFactory<TInstance>): DeadairPlugin<TInstance>;
+//# sourceMappingURL=define.plugin.d.ts.map

package/dist/define.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.plugin.d.ts","sourceRoot":"","sources":["../src/define.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC1I,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,SAAS,SAAS,cAAc,GAAG,cAAc,IAAI,MAAM,SAAS,CAAC;AAE/F,6CAA6C;AAC7C,MAAM,WAAW,aAAa,CAAC,SAAS,SAAS,cAAc,GAAG,cAAc;IAC5E,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,eAAe,GACrD,OAAO,CAAC,oBAAoB,CAAC,GAC7B,OAAO,CAAC,mBAAmB,CAAC,GAC5B,OAAO,CAAC,kBAAkB,CAAC,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEhC,iDAAiD;AACjD,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAE5E,4CAA4C;AAC5C,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEpE,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAE5E,4CAA4C;AAC5C,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEpE,6CAA6C;AAC7C,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG,eAAe,CAAC;AAEtE,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAExE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,SAAS,cAAc,EACzD,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,GAClC,aAAa,CAAC,SAAS,CAAC,CAE1B"}

package/dist/feed.parse.d.ts

@@ -0,0 +1,97 @@
+import type { HostFetchInit, PluginHost } from './plugin.host.js';
+/**
+ * A syndicated feed, as one shape, whichever of the three formats it arrived in.
+ *
+ * The sibling of `plugin.http.ts`, and here for the same reason: every plugin
+ * that reads a feed writes the same normalisation, and none of it is that
+ * plugin's opinion. RSS 2.0 dates an item with `pubDate` in RFC-822, Atom uses
+ * `published` in ISO-8601 and RSS 1.0 uses `dc:date`; a link is an element's
+ * text in two of them and an attribute in the third; a title is a bare string
+ * until somebody sets `type="html"` on it and it becomes an object. None of
+ * that is worth learning twice.
+ *
+ * ## It parses and it does not fetch
+ *
+ * {@link parseFeed} takes a string. That is what makes it testable against real
+ * documents with no host in the way, and it is the half other plugins will
+ * actually reuse. {@link fetchFeed} is the thin convenience on top, and it is
+ * thin deliberately: `host.fetch` already carries the allowlist, the pacing and
+ * the `Retry-After` back-off, so there is nothing left here but a status check.
+ *
+ * Caching and conditional GET (`ETag`, `Last-Modified`) are NOT here. They
+ * belong to whoever is polling — a plugin knows how often its own feeds are
+ * worth asking and this file does not — and putting a cache behind a pure
+ * parser would hide it from the one caller that must not be surprised by it.
+ *
+ * ## Tolerant in one specific direction
+ *
+ * A feed is somebody else's file, served by somebody else's edge, and the ways
+ * it goes wrong are not interesting: a truncated body, an HTML error page with
+ * a 200 on it, an item with no title. So a document that will not parse answers
+ * with no items rather than throwing, and an item missing the one field that
+ * makes it an item is dropped rather than guessed at. What is NOT tolerated is
+ * a bad status, because that is the upstream saying so itself.
+ */
+/** One entry, whatever the feed called it. */
+export interface FeedItem {
+    /**
+     * A stable identifier for this entry, across polls and across restarts.
+     *
+     * The load-bearing field, and the reason it is never absent. Anything that
+     * polls a feed has to tell an arrival from something it has already seen,
+     * and the only alternative to an id is comparing timestamps — which fails
+     * on a publisher that back-dates, re-dates or omits them.
+     *
+     * Taken from `guid`, then Atom's `id`, then the link, and only then a hash
+     * of the title and date. The fallback is what makes the guarantee hold for
+     * a feed that supplies none of the three, and it is a hash rather than an
+     * index because a position in a list changes every time the list does.
+     */
+    id: string;
+    title: string;
+    /** The entry's own words, as plain text. See {@link FEED_SUMMARY_MAX_CHARS}. */
+    summary?: string;
+    url?: string;
+    /** ISO-8601. Never a `Date`, and absent when the feed gave no readable one. */
+    publishedAt?: string;
+    author?: string;
+    categories?: string[];
+}
+/** A feed, and what it holds. */
+export interface ParsedFeed {
+    title?: string;
+    /** Where the publication itself lives, as opposed to any one entry. */
+    homeUrl?: string;
+    /** Newest first where the feed said, and otherwise in the order it listed them. */
+    items: FeedItem[];
+}
+/**
+ * How much of an entry's own words are kept.
+ *
+ * A description is written for a browser and its destination here is a model's
+ * context and possibly a voice, neither of which wants three paragraphs of a
+ * press release. Generous enough to hold a real first paragraph, short enough
+ * that twenty of them still leave room to think.
+ */
+export declare const FEED_SUMMARY_MAX_CHARS = 500;
+/**
+ * A feed document, read.
+ *
+ * Answers with an empty feed rather than throwing, for anything that is not one
+ * — a parse failure, an HTML page, an empty body. The caller's next move is the
+ * same in every case, and a plugin fanning out over five feeds must not lose
+ * four of them to the fifth.
+ */
+export declare function parseFeed(xml: string): ParsedFeed;
+/**
+ * A feed off the network.
+ *
+ * Everything about the request except the status check is `host.fetch`'s: the
+ * allowlist, the pacing, the redirect re-checks, the body caps. What is left is
+ * the one decision a plugin should not be making differently from its
+ * neighbours — which {@link PluginErrorCode} a status means — and that is
+ * `plugin.http.ts`'s ladder, unmodified. A service with its own reading of a
+ * status layers that in front by calling {@link parseFeed} itself.
+ */
+export declare function fetchFeed(host: PluginHost, url: string, init?: HostFetchInit): Promise<ParsedFeed>;
+//# sourceMappingURL=feed.parse.d.ts.map

package/dist/feed.parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.parse.d.ts","sourceRoot":"","sources":["../src/feed.parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACrB;;;;;;;;;;;;OAYG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,KAAK,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAuB1C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAgCjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBxG"}

package/dist/html.text.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Somebody else's markup as something a person could be read aloud.
+ *
+ * Lifted out of `feed.parse.ts` when `article.parse.ts` needed the same two
+ * steps, and shared rather than copied for the reason `match.text.ts` gives
+ * about its own two: a difference between the copies would have one reader
+ * hand a model `&` while the other did not, and nobody would notice until
+ * a voice said it on air.
+ *
+ * Neither function knows anything about feeds or articles. What is here is the
+ * part that is true of any publisher's text: tags are not words, entities are
+ * not punctuation, and a paragraph's worth of whitespace is one space.
+ */
+export declare function decodeEntities(value: string): string;
+/**
+ * Markup as plain text, capped.
+ *
+ * Tags out, entities decoded, whitespace collapsed, length bounded.
+ *
+ * Entities are decoded AFTER the tags come out, and that order matters: an
+ * escaped `<script>` would otherwise be turned into a tag by the decode
+ * and then survive the strip.
+ *
+ * @param maxChars - Where to cut. Absent means keep whatever there is, which is
+ *   what a caller that has already bounded the input wants.
+ */
+export declare function plainText(raw: string, maxChars?: number): string | undefined;
+/**
+ * Text cut at a word boundary where there is one nearby, with an ellipsis.
+ *
+ * A summary that ends mid-word reads as a broken feed rather than as a
+ * truncation, which is the difference between a listener hearing a station
+ * quoting a publisher and one hearing a station malfunction.
+ */
+export declare function truncateWords(value: string, maxChars: number): string;
+/**
+ * The first sentence of a passage, as published, or the whole thing when it is
+ * one sentence.
+ *
+ * Here rather than in a caller because both consumers of prose need it and
+ * neither should be splitting sentences by hand: a station reads the opening
+ * line of a story aloud, and a truncation cuts at the last one that fits.
+ */
+export declare function firstSentence(value: string): string;
+/**
+ * Text cut at the last SENTENCE that fits, with no ellipsis.
+ *
+ * The other kind of cut, and the one that belongs on anything a voice will read
+ * or a model will be told is the story: half a sentence is something to finish,
+ * and a model handed one finishes it out of its own head — which is exactly the
+ * failure a bulletin cannot have. Falls back to {@link truncateWords} when the
+ * first sentence is already longer than the cap, because a hard stop mid-clause
+ * is still better than three paragraphs.
+ */
+export declare function truncateSentences(value: string, maxChars: number): string;
+/**
+ * The longest run of WHOLE sentences within a word count, or nothing.
+ *
+ * The word-counted sibling of {@link truncateSentences}, and the difference
+ * between them is the fallback rather than the unit. That one cuts mid-clause
+ * when the first sentence is already too long, because its caller would rather
+ * have a hard stop than three paragraphs. This one answers `undefined`, because
+ * its caller is choosing between a script and something else it can say
+ * instead, and half a sentence read aloud is worse than either.
+ *
+ * A passage already within the count comes back trimmed and otherwise
+ * untouched, so a caller can put this in front of everything rather than
+ * branching on the length itself.
+ */
+export declare function sentencesWithin(value: string, maxWords: number): string | undefined;
+//# sourceMappingURL=html.text.d.ts.map

package/dist/html.text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.text.d.ts","sourceRoot":"","sources":["../src/html.text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4BH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMrE;AA2BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYzE;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBnF"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export * from './boundary.json.safe.js';
+export * from './capabilities/analysis.js';
+export * from './capabilities/charts.js';
+export * from './capabilities/enrichment.js';
+export * from './capabilities/llm.js';
+export * from './capabilities/mixer.js';
+export * from './capabilities/music.provider.js';
+export * from './capabilities/news.js';
+export * from './capabilities/scrobble.js';
+export * from './capabilities/search.js';
+export * from './capabilities/similarity.js';
+export * from './capabilities/speech.js';
+export * from './capabilities/weather.js';
+export * from './article.parse.js';
+export * from './define.plugin.js';
+export * from './feed.parse.js';
+export * from './html.text.js';
+export * from './match.text.js';
+export * from './plugin.api.version.js';
+export * from './plugin.base.js';
+export * from './plugin.config.fields.js';
+export * from './plugin.config.read.js';
+export * from './plugin.error.js';
+export * from './plugin.host.js';
+export * from './plugin.host.response.js';
+export * from './plugin.http.js';
+export * from './plugin.lifecycle.js';
+export * from './plugin.manifest.js';
+export * from './plugin.permissions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}