@deadair/plugin-sdk 0.2.0

package/dist/capabilities/music.provider.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The `music-provider` kind. A provider declares any subset of the four
+ * sub-capabilities below: `catalog` (it can be searched and browsed), `stream`
+ * (it can get the station audio to play), `steer` (it owns its own audio output
+ * and takes instructions), and `oauth` (it needs a user to authorise it first).
+ * Spotify declares all four; a plain SMB library declares `catalog` and
+ * `stream`.
+ *
+ * Every shape here is JSON-safe. Durations are integers in milliseconds,
+ * never `Date` or `Duration` objects.
+ */
+/** A track as a provider describes it. Deliberately minimal: this is v1 of a public API. */
+export interface ProviderTrack {
+    /** Provider-scoped identifier. Opaque to the host. */
+    id: string;
+    title: string;
+    /** Ordered, primary artist first. Empty array if the provider genuinely has none. */
+    artists: string[];
+    album?: string;
+    durationMs?: number;
+    /** Recording ISRC, when the provider exposes one. The best cross-provider join key. */
+    isrc?: string;
+    artworkUrl?: string;
+    /**
+     * The year this record was first released, as the provider reports it.
+     *
+     * A four-digit year and never a date: what a station asks of a period is which decade a record
+     * belongs to, and a provider that knows the month knows it about THIS release rather than about
+     * the recording. Precision nobody can trust is worse than none, so the field is as coarse as the
+     * question.
+     *
+     * **A reissue usually still carries the ORIGINAL year, and that was worth measuring rather than
+     * assuming.** The pessimistic reading is that a 2011 remaster is dated 2011 by whoever sells it,
+     * which would make a period filter quietly useless for exactly the old records it is most wanted
+     * for. Measured on this station's own library after one sync: of 63 tracks whose title names a
+     * remaster year, 61 came through dated to the original release and 2 to the reissue — `Dazed and
+     * Confused - 1990 Remaster` arrived as 1969 and `Paranoid - 2012 - Remaster` as 1970. So the skew
+     * is real, rare, and not a reason to distrust the field.
+     *
+     * Optional, and absent must read as "the provider did not say" rather than as old or new. A host
+     * filtering by period has to treat an unknown year as ELIGIBLE: a record whose year nobody
+     * recorded is not evidence of the wrong decade, and dropping it would silently shrink a library
+     * to whatever happened to be tagged.
+     *
+     * It exists because the host was throwing this away. Spotify sends `album.release_date` on every
+     * search and playlist row and Subsonic sends `year`, while `deadair.tracks.year` was written only
+     * by a much later enrichment pass — so a station could not be asked for a period until something
+     * else had gone and looked the same records up.
+     */
+    year?: number;
+    /**
+     * How well known the record is, 0 to 100, when the provider has an opinion.
+     *
+     * A RANKING and not a fact: providers compute it differently and none of them says how, so the
+     * only thing it may be used for is ordering rows from the same search against each other. Never
+     * compare it across providers, never show it to a listener, and never gate on a threshold.
+     *
+     * Optional because most sources have nothing like it — a personal library knows what you own,
+     * not what the world plays — and absent must read as "no opinion" rather than as unpopular, or
+     * a station with one ranked provider and one unranked would bury the unranked one's whole
+     * catalogue.
+     *
+     * It exists because of a specific failure: asked for "popular rap songs from the USA", the
+     * model browsed a genre, got two dozen obscure records back in the provider's own order, and
+     * named them. Nothing in the chain could tell a hit from an unknown, so the brief was
+     * unservable however well the model behaved. See `CatalogSearchTool`.
+     */
+    popularity?: number;
+    /**
+     * The parental advisory this copy carries, when the provider reports one.
+     *
+     * A LABEL and not a reading of the words. A provider is passing on the marking a release
+     * carries; nothing here has looked at a lyric. That is why the field is not called `lyrics`,
+     * which stays free for the text itself — a thing a future enrichment source may genuinely fetch,
+     * the way `plugins/wikipedia` fetches article prose.
+     *
+     * It is about LYRICS rather than about LENGTH, which is the other half of the same confusion. A
+     * radio edit is a length cut and may still be explicit, so an edit-length preference is a
+     * separate axis and belongs in a separate field on the day something needs one. Do not widen
+     * this one to carry it.
+     *
+     * Optional because most sources have nothing like it — a file on a disk carries no marking, and
+     * Subsonic has no such field — and absent must read as "the provider did not say" rather than as
+     * clean. A host enforcing a clean-only policy has to demand a positive `'clean'`: treating
+     * silence as consent is how a station promises something it cannot deliver.
+     */
+    advisory?: 'explicit' | 'clean';
+}
+/**
+ * What a source will let the connected account do with one playlist's items.
+ *
+ * Both values are item-scoped, mirroring the endpoint pair they describe
+ * (Spotify's `GET` and `PUT /playlists/{id}/items`). Neither says anything
+ * about the playlist's own name or description: on Spotify a collaborator may
+ * change the items and not the details.
+ */
+export type ProviderPlaylistPermission = 
+/** The source will return this playlist's items. */
+'read'
+/** The source will permit modifying this playlist's items. */
+ | 'edit';
+export interface ProviderPlaylist {
+    id: string;
+    name: string;
+    description?: string;
+    /** Number of tracks, when the provider reports it cheaply. */
+    trackCount?: number;
+    artworkUrl?: string;
+    /**
+     * What the SOURCE permits for the connected account on this playlist, so
+     * the host can avoid offering a call that cannot succeed. Not deadair's own
+     * authorization for the requesting actor, which is a separate question
+     * asked of the permission model, and not a claim that the plugin implements
+     * the action either, which is what the manifest's capabilities declare. All
+     * three have to hold before an action is worth offering.
+     *
+     * Absent and empty mean different things, and the difference matters:
+     *
+     * - `undefined` — the source did not say. Providers with no such split (most
+     *   of them) leave it alone, and a host must read this as "no reason to
+     *   think otherwise" rather than hiding the playlist.
+     * - `[]` — the source was asked and permits nothing.
+     *
+     * Spotify populates it because a listing there mixes playlists the account
+     * owns with playlists it merely follows, and since the February 2026 Web
+     * API changes only the owned half can be read at all.
+     */
+    permissions?: ProviderPlaylistPermission[];
+}
+/** A playable stream, plus how long the URL stays good for. */
+export interface ProviderStream {
+    url: string;
+    /** Unix epoch millis after which `url` must be re-resolved. */
+    expiresAt?: number;
+    /** e.g. `audio/mpeg`. */
+    mimeType?: string;
+}
+export interface SearchTracksOptions {
+    limit?: number;
+    offset?: number;
+    /**
+     * Narrow to records released in a period, inclusive, as four-digit years.
+     *
+     * Either end may stand alone: `yearFrom` with no `yearTo` is "this year onwards".
+     */
+    yearFrom?: number;
+    yearTo?: number;
+}
+export interface ListPlaylistsOptions {
+    limit?: number;
+    offset?: number;
+}
+export interface GetPlaylistTracksOptions {
+    limit?: number;
+    offset?: number;
+}
+/** Search and browse. */
+export interface MusicProviderCatalog {
+    /**
+     * Records matching `query`, narrowed by whatever {@link SearchTracksOptions} carries.
+     *
+     * **A filter you cannot apply means you have nothing to offer for that search — answer `[]`.**
+     * Never ignore one and answer as though it had not been asked for. The caller merges several
+     * providers into one list and cannot tell which rows honoured a filter, so a provider that
+     * quietly drops a period does not degrade the answer, it poisons it: the station asked for
+     * records from 1955 and is handed something else with nothing marking it. Declining costs the caller one
+     * provider's share of a result set it already treats as partial, which is the cheaper mistake by
+     * a wide margin. This is the same reasoning `ProviderTrackLookup` is strict for — a near miss
+     * here does not raise an error, it airs the wrong record.
+     *
+     * `limit` is a TOTAL, not a page size. Page internally if the upstream's own ceiling is lower.
+     */
+    searchTracks(query: string, options?: SearchTracksOptions): Promise<ProviderTrack[]>;
+    /** Resolves to `undefined` when the id is unknown to the provider. */
+    getTrack(trackId: string): Promise<ProviderTrack | undefined>;
+    listPlaylists(options?: ListPlaylistsOptions): Promise<ProviderPlaylist[]>;
+    getPlaylistTracks(playlistId: string, options?: GetPlaylistTracksOptions): Promise<ProviderTrack[]>;
+}
+/**
+ * Getting the station actual audio: one method, because it is one job.
+ *
+ * A provider that cannot answer it plays its own audio and never hands anything
+ * over, which is what "steer only" means (a remote Spotify Connect device, say).
+ *
+ * How the audio reaches the player is the provider's business, not the caller's.
+ * Most mint a URL out of their own head. A provider whose audio is reachable
+ * only to a process speaking a protocol it does not — Spotify's, whose tracks
+ * come off the CDN encrypted — lends the station's fetcher a login through
+ * `host.trackFetcher` and returns the URL that comes back. Both answer here.
+ */
+export interface MusicProviderStream {
+    /**
+     * Turn a track id into something the host can actually play: a complete URL
+     * that carries its own authentication, because the player fetches it with no
+     * headers from us.
+     *
+     * Optional only so a "steer only" provider can leave it out. Resolves to
+     * `undefined` when the provider is not connected yet, or when this station
+     * has nothing that can serve the track: the host reads that as "not
+     * available", skips the item, and holds nothing against the plugin.
+     */
+    resolveStreamUrl?(trackId: string): Promise<ProviderStream | undefined>;
+}
+export type PlaybackStatus = 'playing' | 'paused' | 'stopped';
+export interface PlaybackState {
+    status: PlaybackStatus;
+    /** The track currently loaded, if any. */
+    trackId?: string;
+    /** Playhead position in ms. */
+    positionMs?: number;
+    durationMs?: number;
+}
+/**
+ * Transport control, for providers that own their own audio output: deadair
+ * tells them what to do rather than playing anything itself.
+ *
+ * Named for what the plugin is asked to do, not for what the station calls the
+ * job. deadair's own `playout` module is the other end of this — it owns the
+ * running order and drives the player — so a capability by that name would have
+ * meant the opposite thing to anyone reading both.
+ */
+export interface MusicProviderSteer {
+    /** Append track ids to the provider's own queue. */
+    enqueue(trackIds: string[]): Promise<void>;
+    /** Start (or resume). With `trackId`, start that track immediately. */
+    play(trackId?: string): Promise<void>;
+    pause(): Promise<void>;
+    skip(): Promise<void>;
+    getPlaybackState(): Promise<PlaybackState>;
+}
+/**
+ * Authorisation-code flow. The host owns the redirect endpoint and calls
+ * `handleCallback` with the query parameters it received.
+ */
+export interface MusicProviderOAuth {
+    getAuthorizeUrl(state: string): Promise<string>;
+    handleCallback(params: Record<string, string>): Promise<void>;
+}
+/**
+ * Convenience alias for a provider implementing every sub-capability.
+ * Implement the individual interfaces instead when you only support some.
+ */
+export interface MusicProvider extends MusicProviderCatalog, MusicProviderStream, MusicProviderSteer, MusicProviderOAuth {
+}
+//# sourceMappingURL=music.provider.d.ts.map

package/dist/capabilities/music.provider.d.ts.map

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

package/dist/capabilities/news.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The `news` kind. A news plugin answers "what happened", as entries somebody
+ * else published.
+ *
+ * ## It reports, and it does not schedule
+ *
+ * Nothing here says anything about a break, a bulletin or a running order. A
+ * plugin hands over what its sources published and the station decides whether
+ * that is worth saying, when, and in whose voice — the same boundary
+ * `capabilities/charts.ts` keeps for the same reason. A source able to put
+ * itself on air is a source that can talk over an operator's decisions.
+ *
+ * ## Several plugins, several newsrooms
+ *
+ * Unlike `enrichment`, this is not a fan-out that merges: two news services do
+ * not produce one better story, they produce two stories. So there is no
+ * `priority` here, and the host qualifies every {@link NewsFeedDescriptor.id}
+ * with the plugin that offered it — two services will both call something
+ * `world`.
+ *
+ * ## `id` + `publishedAt` + `since` are a de-duplication contract
+ *
+ * The one rule in this file that is not obvious from the shapes, and the one
+ * that anything polling depends on: **a {@link NewsItem.id} is stable for the
+ * same entry across calls**, so a caller can tell an arrival from something it
+ * has already seen without holding state on the plugin's behalf. A plugin must
+ * not renumber, re-order or synthesise ids per call, and must not let a cache
+ * of its own hide an entry that {@link NewsQuery.since} asked for. Both are
+ * free if the plugin builds its items with `feed.parse.ts`, which is where that
+ * ladder lives.
+ *
+ * Every shape here is JSON-safe.
+ */
+/**
+ * One feed this plugin can serve.
+ *
+ * `id` is scoped to this plugin and needs to be unique only within it. The host
+ * qualifies it before anything outside sees it, so a short flat id is right.
+ */
+export interface NewsFeedDescriptor {
+    id: string;
+    /** What to call it in a list an operator reads, e.g. `World news`. */
+    name: string;
+    /** Broad subject, e.g. `world`, `sport`, `technology`. The publisher's own word for it. */
+    category?: string;
+    /** ISO 639-1, when the plugin knows what language the entries are in. */
+    language?: string;
+    description?: string;
+    /**
+     * How often this source is worth asking, in milliseconds.
+     *
+     * A hint from the only party that knows: a wire service publishes minute by
+     * minute and a weekly column does not. Nothing is obliged to honour it, and
+     * a plugin that has no opinion leaves it out rather than inventing one.
+     */
+    pollHintMs?: number;
+}
+/** What a news source is asked for. */
+export interface NewsQuery {
+    /**
+     * A {@link NewsFeedDescriptor.id} this plugin offered, or absent for all of
+     * them merged newest first.
+     *
+     * Absent is the common case and is why it is optional: "what is going on"
+     * is one question, and making a caller pick a feed first would cost a model
+     * a whole round trip to learn ids it has no basis for choosing between.
+     */
+    feedId?: string;
+    /** How many entries to return. A plugin may return fewer; it must not return more. */
+    limit: number;
+    /**
+     * Only entries published after this instant, as an ISO-8601 string. Never a
+     * `Date`.
+     *
+     * How a caller asks what is new since it last looked. A plugin that cannot
+     * filter upstream filters what it got rather than ignoring this, because a
+     * caller cannot tell "there is nothing new" from "this was not applied".
+     */
+    since?: string;
+    /**
+     * `true` when the caller will not read {@link NewsItem.content}, so a plugin
+     * that would go and fetch one should not bother.
+     *
+     * A hint about COST rather than about shape: a plugin that has the story
+     * already, because the entry carried it, still sends it. What this asks it
+     * to skip is work it would otherwise do on the caller's behalf — for a feed
+     * reader that means following each entry's link and reading the publisher's
+     * page, which is an order of magnitude more expensive than the feed itself
+     * and is why this exists.
+     *
+     * Absent means the ordinary thing, so a plugin that ignores this is slow
+     * rather than wrong, and a caller that forgets it gets stories it does not
+     * need. That is the right way round: the console asked for a page of
+     * headlines and waited three seconds for article bodies it never drew.
+     */
+    headlinesOnly?: boolean;
+}
+/** One published entry. */
+export interface NewsItem {
+    /** Stable across calls. See the de-duplication contract in this file's header. */
+    id: string;
+    /** Which feed it came from, as the plugin's own unqualified id. */
+    feedId: string;
+    /** That feed's name, so a caller reading one merged list can say where a story came from. */
+    feedName: string;
+    title: string;
+    /**
+     * The entry's own words, as PLAIN TEXT.
+     *
+     * Never markup. This ends up in a model's context and possibly in a
+     * speaking voice, and a `<p>` reaching either of those is a bug that is
+     * only noticed on air. `parseFeed` in `feed.parse.ts` already guarantees it.
+     */
+    summary?: string;
+    /**
+     * The story itself, as PLAIN TEXT, when the plugin could read it.
+     *
+     * Distinct from {@link summary} rather than replacing it, because they are
+     * two different things a publisher wrote: a summary is the teaser attached
+     * to the entry and this is the article. In practice the teaser is often one
+     * sentence restating the title, which is why a caller wanting to say what
+     * HAPPENED needs somewhere else to look.
+     *
+     * Still the publisher's own words in the publisher's own order, never a
+     * plugin's paraphrase. A plugin fetches and the host thinks — the same
+     * boundary `capabilities/enrichment.ts` keeps with `SourceDocument`, for
+     * the same reason: only the host can check a claim against the text it came
+     * from, and prose that has been through a plugin's own summariser is prose
+     * nothing can check.
+     *
+     * Absent is entirely ordinary. An entry that links to an audio piece, a
+     * page a plugin was refused, and one it had no budget left to read all
+     * arrive the same way, and every caller's fallback is the entry's own
+     * words. `extractArticle` in `article.parse.ts` is what produces this for
+     * a plugin reading pages.
+     */
+    content?: string;
+    url?: string;
+    /** ISO-8601. Never a `Date`, and absent when the source published no readable one. */
+    publishedAt?: string;
+    /** The publisher's own labels, unmapped. Useful for filtering, never authoritative. */
+    categories?: string[];
+}
+/**
+ * Implemented by a `news` plugin.
+ */
+export interface NewsProvider {
+    /**
+     * What this plugin can serve, right now.
+     *
+     * Asked per call rather than cached by the host, for the reason
+     * `ChartsProvider.listCharts` is: an operator reconfiguring a plugin
+     * reinitializes it, and a feed list built from a config field would
+     * otherwise be a boot snapshot of a setting that has since changed.
+     *
+     * An empty array is an ordinary answer — a plugin nobody has pointed at a
+     * feed yet has nothing to offer — and is not a failure.
+     */
+    listFeeds(): Promise<NewsFeedDescriptor[]>;
+    /**
+     * Entries, newest first.
+     *
+     * Return `[]` for a `feedId` you do not recognise rather than throwing: the
+     * host asks the plugin that named the id, so an unknown one means the menu
+     * moved underneath a caller, which is a stale request and not a fault. A
+     * source that could not be read is the same answer for the same reason, and
+     * one failing feed must not cost the others.
+     */
+    fetchItems(query: NewsQuery): Promise<NewsItem[]>;
+}
+//# sourceMappingURL=news.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"news.d.ts","sourceRoot":"","sources":["../../src/capabilities/news.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,2BAA2B;AAC3B,MAAM,WAAW,QAAQ;IACrB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;;;;;;OAUG;IACH,SAAS,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE3C;;;;;;;;OAQG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACrD"}

package/dist/capabilities/scrobble.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The `scrobble` kind. A scrobble plugin reports what the station played to
+ * somebody else's service.
+ *
+ * ## The only capability that SENDS
+ *
+ * Everything else a plugin does is a read: enrichment asks an upstream what it
+ * knows, a chart asks what is popular, a provider asks for audio. This publishes
+ * the station's own listening to an account the operator holds, which makes it
+ * the one place where getting it wrong writes to somebody else's records rather
+ * than producing a worse hour.
+ *
+ * Three things follow from that and are worth knowing before implementing one.
+ *
+ * **Late is fine and lost is not.** The host queues every play durably and
+ * retries with a backoff, so a plugin never has to hold anything: answer for the
+ * batch you were given and say what happened to it.
+ *
+ * **{@link ScrobbleRejection.retryable} is the field that matters.** "The service
+ * was down" and "that timestamp is too old to accept" are opposite facts, and a
+ * queue that cannot tell them apart either loses plays or retries a permanent
+ * rejection forever. The plugin classifies, because only the plugin knows what
+ * its upstream meant; the host obeys.
+ *
+ * **{@link ScrobbleProvider.accepting} is how an operator says no.** A service
+ * that also does something else — Last.fm is enrichment, charts, similarity and
+ * this — is one installed plugin, and wanting its tags without sending it your
+ * listening is an ordinary position. Since `plugin_configs.plugin_id` is a
+ * primary key, it cannot be expressed by installing twice, and since capabilities
+ * are fixed when the plugin is written it cannot be expressed by the manifest
+ * either. So it is a config field, read back through one optional method.
+ *
+ * Every shape here is JSON-safe.
+ */
+/** One record the station played. */
+export interface ScrobblePlay {
+    title: string;
+    /**
+     * The LEAD artist, as the catalog credits it.
+     *
+     * Not a joined credit line, for the reason every other capability here gives:
+     * a scrobbling service matches on artist and title, and "A, B & C" matches
+     * nothing. {@link albumArtist} is where a compilation's own credit goes.
+     */
+    artist: string;
+    album?: string;
+    /** The record's own credit, where it differs from the track's. */
+    albumArtist?: string;
+    /** Integer milliseconds. Some services use it to decide whether a play counts. */
+    durationMs?: number;
+    trackNumber?: number;
+    /** MusicBrainz recording id, when the catalog has resolved one. */
+    mbid?: string;
+    /**
+     * When it started, as Unix epoch MILLISECONDS. Never a `Date`.
+     *
+     * Milliseconds because that is what the rest of this SDK uses; a service
+     * wanting seconds divides. It is the moment the record went to air rather
+     * than the moment this call was made, and the difference is the whole reason
+     * the host queues: a play sent an hour late is still a play at the time it
+     * happened.
+     */
+    playedAt: number;
+}
+/** Why one play in a batch was refused. */
+export interface ScrobbleRejection {
+    /** Which play, as its index in the batch that was submitted. */
+    index: number;
+    /** What the upstream said, summarized by the plugin. Never the raw body. */
+    reason: string;
+    /**
+     * Whether sending it again could work.
+     *
+     * `true` for a timeout, a 5xx, a rate limit. `false` for a timestamp the
+     * service will not accept, a malformed record, a revoked authorization. When
+     * in doubt, say `false`: a play retried forever is a queue that never drains,
+     * and one dropped is one listen missing from a history nobody audits.
+     */
+    retryable: boolean;
+}
+/** What became of one batch. */
+export interface ScrobbleResult {
+    /** How many the service took. */
+    accepted: number;
+    /** The ones it did not, each said to be worth retrying or not. */
+    rejected: ScrobbleRejection[];
+}
+/**
+ * Implemented by a `scrobble` plugin.
+ */
+export interface ScrobbleProvider {
+    /**
+     * How many plays this plugin will take in one {@link scrobble} call.
+     *
+     * The host chunks to it. Absent means the host picks a modest default, which
+     * is the right answer for a service with no published batch limit.
+     */
+    maxBatchSize?: number;
+    /**
+     * Report plays that have already happened.
+     *
+     * The batch is ordered oldest first. Answer for every entry: anything neither
+     * counted in `accepted` nor listed in `rejected` is treated as accepted, since
+     * a plugin that quietly dropped one is a worse outcome than a duplicate.
+     *
+     * THROW only when the whole batch failed for one reason — no credentials, the
+     * service unreachable — which the host treats as retryable for all of them.
+     * A per-play problem belongs in `rejected`, where it can be classified.
+     */
+    scrobble(plays: ScrobblePlay[]): Promise<ScrobbleResult>;
+    /**
+     * Say what is playing right now.
+     *
+     * Optional, and deliberately not part of the durable path: it is worthless
+     * late, so the host sends it once, at the moment the record goes to air, and
+     * never retries or queues it. A plugin should treat a failure here as
+     * unimportant.
+     */
+    nowPlaying?(play: ScrobblePlay): Promise<void>;
+    /**
+     * Whether this destination currently wants the station's plays.
+     *
+     * Optional, and ABSENT MEANS YES — a plugin that exists only to scrobble
+     * never has to write it. Implement it when the same plugin does other things
+     * and an operator might want those without this.
+     *
+     * Asked before anything is queued, so answering `false` means nothing
+     * accumulates rather than a queue that drains into a discard. Keep it cheap:
+     * it is a config read, not a call to the service.
+     */
+    accepting?(): Promise<boolean>;
+}
+//# sourceMappingURL=scrobble.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrobble.d.ts","sourceRoot":"","sources":["../../src/capabilities/scrobble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,qCAAqC;AACrC,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAC9B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC3B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC"}