@omelhorsite/sdk 0.17.0 → 0.18.0

package/dist/types/auth/tokens.d.ts

@@ -93,7 +93,7 @@ export interface TokenStore {
  * narrowest set the product actually uses: every extra scope makes the
  * approval page scarier for no benefit.
  */
-export declare const OMS_SCOPES: readonly ["openid", "profile", "email", "tools:read", "tools:write", "storage:read", "storage:write", "tickets:write", "llm", "blogs:read", "blogs:write", "news:read", "news:write", "cron:read", "cron:write"];
+export declare const OMS_SCOPES: readonly ["openid", "profile", "email", "tools:read", "tools:write", "storage:read", "storage:write", "tickets:write", "llm", "blogs:read", "blogs:write", "news:read", "news:write", "cron:read", "cron:write", "cron:run", "bots:read", "bots:write"];
 /** One of {@link OMS_SCOPES}. */
 export type OmsScope = (typeof OMS_SCOPES)[number];
 /** Refresh this long before the real expiry unless the host says otherwise. */

package/dist/types/client.d.ts

@@ -20,6 +20,7 @@ import { AuthSessionsNamespace } from "./resources/auth/sessions";
 import { ChestsNamespace } from "./resources/chests";
 import { ContentNamespace } from "./resources/content";
 import { CronNamespace } from "./resources/cron";
+import { BotsNamespace } from "./resources/bots";
 import { DynamicQrsNamespace } from "./resources/dynamicQrs";
 import { FormsNamespace } from "./resources/forms";
 import { IpLookupNamespace } from "./resources/ipLookup";
@@ -186,6 +187,8 @@ export declare class Oms {
     readonly llm: LlmNamespace;
     /** TypeScript scripts the server runs on a schedule as the signed-in person. */
     readonly cron: CronNamespace;
+    /** Messaging channels (Telegram bots): contacts, conversations, sending. */
+    readonly bots: BotsNamespace;
     /**
      * The WebSocket connection: playback handoff, jams, notifications, job
      * progress. Opens nothing until {@link RealtimeNamespace.connect} is called,

package/dist/types/resources/admin/llm.d.ts

@@ -100,6 +100,22 @@ export interface LlmProviderTestResult {
     readonly latency_ms?: number;
     readonly error?: string;
 }
+/**
+ * One upstream serving a model on OpenRouter: the same model at a different
+ * price and health per real provider. `status` is `0` when healthy and
+ * negative while OpenRouter steers traffic away from it.
+ */
+export interface LlmModelEndpoint {
+    /** The routing tag, e.g. `"openai/flex"`; what goes in `metadata.routing.order`. */
+    readonly tag: string;
+    readonly name: string;
+    readonly input_price_per_million: number | null;
+    readonly output_price_per_million: number | null;
+    readonly context_window: number | null;
+    readonly max_output_tokens: number | null;
+    readonly status: number;
+    readonly capabilities: LlmCapabilities;
+}
 export interface TestLlmProviderInput {
     /** A `model_id` of that provider; defaults to its first enabled model. */
     readonly modelId?: string;
@@ -149,6 +165,13 @@ export interface CreateLlmModelInput {
     readonly free?: boolean;
     readonly capabilities?: LlmCapabilities;
     readonly limits?: LlmLimits;
+    /**
+     * Free-form notes on the model. One key is read: `routing`, the OpenRouter
+     * `provider` object sent with every request to this model, for instance
+     * `{ order: ["openai/flex"], allow_fallbacks: false }` to pin the cheapest
+     * upstream. Pick a tag from {@link AdminLlmProvidersNamespace.modelEndpoints}.
+     */
+    readonly metadata?: JsonObject;
 }
 /** The provider and the `model_id` are fixed after creation. */
 export type UpdateLlmModelInput = Partial<Omit<CreateLlmModelInput, "llmProviderId" | "modelId">>;
@@ -231,6 +254,17 @@ export declare class AdminLlmProvidersNamespace extends Resource {
     availableModels(id: Id, input?: {
         fresh?: boolean;
     }, options?: RequestOptions): Promise<LlmAvailableModel[]>;
+    /**
+     * `GET /admin/llm_providers/:id/model_endpoints` - the upstreams that serve
+     * a model on OpenRouter, cheapest first, with their prices. Empty on any
+     * other kind of provider. Cached for ten minutes; `fresh` skips the cache.
+     *
+     * @throws {OmsApiError} 400 without `modelId`; 502 when OpenRouter does not answer.
+     */
+    modelEndpoints(id: Id, input: {
+        modelId: string;
+        fresh?: boolean;
+    }, options?: RequestOptions): Promise<LlmModelEndpoint[]>;
     /** One tiny completion, to check the key, the URL and a model. */
     test(id: Id, input?: TestLlmProviderInput, options?: RequestOptions): Promise<LlmProviderTestResult>;
 }

package/dist/types/resources/bots.d.ts

@@ -0,0 +1,394 @@
+/**
+ * The `bots` namespace: messaging channels (Telegram bots for now), the
+ * contacts who talk to them and the conversations, plus sending.
+ *
+ * A channel is a bot token the account connected; the server validates it,
+ * registers a webhook and from then on every message the bot receives lands
+ * here as a {@link BotContact} and a {@link BotMessage}. Sending is
+ * {@link BotMessagesNamespace.send}: the server talks to Telegram and records
+ * the outgoing message with its source, so an inbox shows what went where.
+ *
+ * Needs the `bots:read` scope to read and `bots:write` to send or connect.
+ */
+import { Resource } from "../http";
+import type { ApiClient } from "../http";
+import type { ListParams } from "../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../types";
+export declare const BOT_CHANNEL_KINDS: readonly ["telegram"];
+export type BotChannelKind = (typeof BOT_CHANNEL_KINDS)[number];
+export declare const BOT_CHANNEL_HEALTHS: readonly ["unknown", "ok", "error"];
+export type BotChannelHealth = (typeof BOT_CHANNEL_HEALTHS)[number];
+/** What the bot does: `inbox` keeps the conversations and lets the API send; `responder` answers on the owner's behalf. */
+export declare const BOT_PLUGINS: readonly ["inbox", "responder"];
+export type BotPlugin = (typeof BOT_PLUGINS)[number];
+/** Telegram's own cap on a message's text. Longer is a `400`. */
+export declare const BOT_MESSAGE_MAX_TEXT = 4096;
+/** A connected bot. The token never comes back: only whether one is stored. */
+export interface BotChannel {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly name: string;
+    readonly kind: BotChannelKind;
+    readonly plugin: BotPlugin;
+    /** The bot's own handle on the platform, filled from the token. */
+    readonly username: string | null;
+    /** The bot's own id on the platform. */
+    readonly external_id: string | null;
+    readonly enabled: boolean;
+    readonly health: BotChannelHealth;
+    readonly last_error: string | null;
+    readonly last_message_at: Timestamp | null;
+    readonly token_set: boolean;
+    /** Where the platform delivers the bot's updates. */
+    readonly webhook_url: string;
+}
+/** `GET /bot_channels/:id` adds two counters. */
+export interface BotChannelDetail extends BotChannel {
+    readonly contacts_count: number;
+    readonly unread_count: number;
+}
+export interface CreateBotChannelInput {
+    readonly name: string;
+    /** The token the platform's bot factory gave you (Telegram: @BotFather). */
+    readonly token: string;
+    readonly kind?: BotChannelKind;
+    /** Defaults to `inbox`. */
+    readonly plugin?: BotPlugin;
+    readonly enabled?: boolean;
+}
+/** A new `token` reconnects the channel; omit it to keep the stored one. */
+export type UpdateBotChannelInput = Partial<CreateBotChannelInput>;
+/** What the platform reports about the bot and its webhook. */
+export type BotChannelStatus = {
+    readonly ok: true;
+    readonly username: string | null;
+    readonly webhook_url: string;
+    readonly webhook_set: boolean;
+    readonly pending_updates: number;
+    readonly last_error: string | null;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare const BOT_CHANNEL_FILTER_COLUMNS: readonly ["name", "kind", "enabled"];
+export interface ListBotChannelsParams extends ListParams<(typeof BOT_CHANNEL_FILTER_COLUMNS)[number]> {
+}
+export declare const BOT_CONTACT_KINDS: readonly ["private", "group", "supergroup", "channel"];
+export type BotContactKind = (typeof BOT_CONTACT_KINDS)[number];
+/** Someone (or some group) that talked to a channel. */
+export interface BotContact {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    /** The chat id on the platform. */
+    readonly external_id: string;
+    readonly kind: BotContactKind;
+    readonly name: string | null;
+    readonly username: string | null;
+    readonly tags: string[];
+    /** The contact blocked the bot or left the group: sending is refused. */
+    readonly blocked: boolean;
+    readonly last_message_at: Timestamp | null;
+    readonly last_direction: "in" | "out" | null;
+    readonly last_text: string | null;
+    readonly messages_count: number;
+    readonly unread_count: number;
+    /** The responder could not answer; `note` says what was missing. */
+    readonly needs_human: boolean;
+    readonly note: string | null;
+    readonly handled_until: Timestamp | null;
+    /** The name, or `@username`, or the chat id. */
+    readonly display_name: string;
+}
+export interface UpdateBotContactInput {
+    readonly name?: string | null;
+    readonly tags?: readonly string[];
+    readonly needs_human?: boolean;
+    readonly note?: string | null;
+}
+export declare const BOT_CONTACT_FILTER_COLUMNS: readonly ["bot_channel_id", "external_id", "username", "kind", "blocked"];
+export interface ListBotContactsParams extends ListParams<(typeof BOT_CONTACT_FILTER_COLUMNS)[number]> {
+    /** Only contacts of one channel. */
+    readonly channelId?: Id;
+}
+export type BotMessageDirection = "in" | "out";
+/** `contact` came in; `human` was sent from the inbox; `api` by a token (a script, the CLI); `bot` by the responder. */
+export type BotMessageSource = "contact" | "human" | "api" | "bot";
+export interface BotMessage {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    readonly bot_contact_id: Id;
+    readonly direction: BotMessageDirection;
+    readonly source: BotMessageSource;
+    readonly text: string;
+    readonly external_id: string | null;
+    readonly sent_at: Timestamp;
+    /** Set when the platform refused the send; the row stays so the thread shows it. */
+    readonly error: string | null;
+}
+export declare const BOT_MESSAGE_FILTER_COLUMNS: readonly ["bot_channel_id", "bot_contact_id", "direction", "source"];
+export interface ListBotMessagesParams extends ListParams<(typeof BOT_MESSAGE_FILTER_COLUMNS)[number]> {
+    readonly contactId?: Id;
+    readonly channelId?: Id;
+}
+/** `text` for the text as typed; `html` for Telegram's HTML subset (bold, links, blockquote). */
+export type BotMessageFormat = "text" | "html";
+export type SendBotMessageInput = ({
+    readonly contactId: Id;
+    readonly channelId?: undefined;
+    readonly externalId?: undefined;
+} | {
+    /** A contact that has not written yet, by channel and chat id. */
+    readonly channelId: Id;
+    readonly externalId: string;
+    readonly contactId?: undefined;
+}) & {
+    readonly text: string;
+    readonly format?: BotMessageFormat;
+};
+/** The responder of a channel whose plugin is `responder`. `id` is null until it is first saved. */
+export interface BotResponder {
+    readonly id: Id | null;
+    readonly created_at: Timestamp | null;
+    readonly updated_at: Timestamp | null;
+    readonly bot_channel_id: Id;
+    readonly enabled: boolean;
+    readonly system_prompt: string;
+    readonly knowledge: string;
+    readonly signature: string;
+    /** An LLM model id or model_id; null for the account's default. */
+    readonly model: string | null;
+    /** Runs per day, at hours drawn inside the window. */
+    readonly slots_per_day: number;
+    readonly window_start: string;
+    readonly window_end: string;
+    readonly timezone: string;
+    readonly history_limit: number;
+    readonly language: string;
+    readonly facts_count: number;
+    readonly sources_count: number;
+    readonly waiting_count: number;
+}
+export type UpdateBotResponderInput = Partial<Pick<BotResponder, "enabled" | "system_prompt" | "knowledge" | "signature" | "model" | "slots_per_day" | "window_start" | "window_end" | "timezone" | "history_limit" | "language">>;
+export type BotFactSource = "manual" | "chat" | "learned";
+export interface BotFact {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    readonly text: string;
+    readonly valid_from: string | null;
+    readonly valid_until: string | null;
+    readonly source: BotFactSource;
+    readonly bot_contact_id: Id | null;
+    readonly active: boolean;
+}
+export interface CreateBotFactInput {
+    readonly channelId: Id;
+    readonly text: string;
+    readonly valid_from?: string | null;
+    readonly valid_until?: string | null;
+}
+export type UpdateBotFactInput = Partial<Omit<CreateBotFactInput, "channelId">>;
+export declare const BOT_FACT_FILTER_COLUMNS: readonly ["bot_channel_id", "source", "bot_contact_id"];
+export interface ListBotFactsParams extends ListParams<(typeof BOT_FACT_FILTER_COLUMNS)[number]> {
+    readonly channelId?: Id;
+}
+export interface BotSource {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    readonly name: string;
+    readonly url: string;
+    readonly description: string | null;
+}
+export interface CreateBotSourceInput {
+    readonly channelId: Id;
+    readonly name: string;
+    readonly url: string;
+    readonly description?: string | null;
+}
+export type UpdateBotSourceInput = Partial<Omit<CreateBotSourceInput, "channelId">>;
+export declare const BOT_SOURCE_FILTER_COLUMNS: readonly ["bot_channel_id"];
+export interface ListBotSourcesParams extends ListParams<(typeof BOT_SOURCE_FILTER_COLUMNS)[number]> {
+    readonly channelId?: Id;
+}
+export type BotResponderRunStatus = "pending" | "running" | "done" | "failed" | "skipped";
+export interface BotResponderRun {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    readonly status: BotResponderRunStatus;
+    readonly trigger: "schedule" | "manual";
+    readonly scheduled_at: Timestamp;
+    readonly started_at: Timestamp | null;
+    readonly finished_at: Timestamp | null;
+    readonly replied: number;
+    readonly escalated: number;
+    readonly error: string | null;
+}
+export declare const BOT_RUN_FILTER_COLUMNS: readonly ["bot_channel_id", "status", "trigger"];
+export interface ListBotResponderRunsParams extends ListParams<(typeof BOT_RUN_FILTER_COLUMNS)[number]> {
+    readonly channelId?: Id;
+}
+/** One line of the owner's conversation with the responder; `meta` says what a reply did. */
+export interface BotOwnerMessage {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly bot_channel_id: Id;
+    readonly role: "user" | "assistant";
+    readonly text: string;
+    readonly meta: {
+        readonly facts?: readonly Id[];
+        readonly removed?: readonly Id[];
+        readonly sources?: readonly Id[];
+        readonly retrying?: boolean;
+    };
+}
+export interface BotOwnerChat {
+    readonly messages: BotOwnerMessage[];
+    /** When the current session (no pause over two hours) started; null when there is none. */
+    readonly session_started_at: Timestamp | null;
+    /** Contacts the responder could not answer. */
+    readonly waiting: BotContact[];
+}
+export interface BotOwnerChatTurn {
+    readonly reply: BotOwnerMessage;
+    readonly facts: BotFact[];
+    readonly removed: Id[];
+    readonly sources: BotSource[];
+    /** Facts were saved while contacts were waiting: they are being answered in the background. */
+    readonly retrying: boolean;
+}
+export type BotReplyOutcome = "replied" | "escalated" | "skipped";
+export interface BotReplyResult {
+    readonly result: BotReplyOutcome;
+    readonly contact: BotContact;
+}
+export interface BotTeachResult {
+    readonly learned: BotFact[];
+    readonly contact: BotContact;
+}
+/** `/bot_channels` - the connected bots. */
+export declare class BotChannelsNamespace extends Resource {
+    /** `GET /bot_channels` - your channels, oldest first. */
+    list(params?: ListBotChannelsParams, options?: RequestOptions): Promise<Paginated<BotChannel>>;
+    /** `GET /bot_channels/:id`. 404 when it is not yours. */
+    get(id: Id, options?: RequestOptions): Promise<BotChannelDetail>;
+    /**
+     * `POST /bot_channels` - connect a bot. The server checks the token with the
+     * platform and registers the webhook before answering `201`.
+     *
+     * @throws {OmsApiError} 400 when the platform refuses the token, the name
+     *   repeats, or the account is at its channel limit.
+     */
+    create(input: CreateBotChannelInput, options?: RequestOptions): Promise<BotChannelDetail>;
+    /** `PATCH /bot_channels/:id`. A new `token` reconnects; a blank one is ignored. */
+    update(id: Id, input: UpdateBotChannelInput, options?: RequestOptions): Promise<BotChannelDetail>;
+    /** `DELETE /bot_channels/:id` - unregisters the webhook, drops contacts and messages. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /** `POST /bot_channels/:id/test` - what the platform says about the bot and the webhook. */
+    test(id: Id, options?: RequestOptions): Promise<BotChannelStatus>;
+}
+/** `/bot_contacts` - who talked to your channels. Read, tag, mark read. */
+export declare class BotContactsNamespace extends Resource {
+    /** `GET /bot_contacts` - most recently active first. */
+    list(params?: ListBotContactsParams, options?: RequestOptions): Promise<Paginated<BotContact>>;
+    get(id: Id, options?: RequestOptions): Promise<BotContact>;
+    /** `PATCH /bot_contacts/:id` - the name you give them and the tags. */
+    update(id: Id, input: UpdateBotContactInput, options?: RequestOptions): Promise<BotContact>;
+    /** `POST /bot_contacts/:id/read` - the unread counter to zero. */
+    markRead(id: Id, options?: RequestOptions): Promise<BotContact>;
+    /**
+     * `POST /bot_contacts/:id/bot_reply` - the responder handles this conversation now.
+     *
+     * @throws {OmsApiError} 400 when the channel's plugin is not the responder or it was never saved; 502 when the model or the platform failed.
+     */
+    botReply(id: Id, options?: RequestOptions): Promise<BotReplyResult>;
+    /**
+     * `POST /bot_contacts/:id/teach` - give the responder what it was missing: the general
+     * part is kept as facts, the contact gets an answer, the others waiting are retried.
+     */
+    teach(id: Id, hint: string, options?: RequestOptions): Promise<BotTeachResult>;
+    /** `DELETE /bot_contacts/:id` - the contact and its messages. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/** `/bot_messages` - the conversations, and sending. */
+export declare class BotMessagesNamespace extends Resource {
+    /** `GET /bot_messages` - newest first; pass `order: "sent_at:asc"` for a thread top-down. */
+    list(params?: ListBotMessagesParams, options?: RequestOptions): Promise<Paginated<BotMessage>>;
+    get(id: Id, options?: RequestOptions): Promise<BotMessage>;
+    /**
+     * `POST /bot_messages` - send. The server talks to the platform and records
+     * the message with source `api` (a token) or `human` (a session).
+     *
+     * @throws {OmsApiError} 422 when the contact blocked the bot; 429 at the daily
+     *   limit; 502 when the platform refused (the row is kept with `error`).
+     */
+    send(input: SendBotMessageInput, options?: RequestOptions): Promise<BotMessage>;
+    /** `DELETE /bot_messages/:id` - one row out of the thread. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/** `/bot_channels/:id/responder` - the responder plugin of a channel. */
+export declare class BotRespondersNamespace extends Resource {
+    /** @throws {OmsApiError} 400 when the channel's plugin is not the responder. */
+    get(channelId: Id, options?: RequestOptions): Promise<BotResponder>;
+    /** `PATCH /bot_channels/:id/responder` - creates it on first save. */
+    update(channelId: Id, input: UpdateBotResponderInput, options?: RequestOptions): Promise<BotResponder>;
+    /**
+     * `POST /bot_channels/:id/responder/run` - answer the pending conversations now, outside the schedule.
+     *
+     * @throws {OmsApiError} 400 when a run is already open or the responder was never saved.
+     */
+    run(channelId: Id, options?: RequestOptions): Promise<BotResponderRun>;
+}
+/** `/bot_channels/:id/owner_chat` - the owner talking to the responder: teach, ask, correct, delete, point to sources. */
+export declare class BotOwnerChatNamespace extends Resource {
+    get(channelId: Id, options?: RequestOptions): Promise<BotOwnerChat>;
+    /**
+     * `POST /bot_channels/:id/owner_chat` - one turn. The model's decisions are applied before the answer comes back.
+     *
+     * @throws {OmsApiError} 400 when the channel's plugin is not the responder or it was never saved; 502 when the model failed.
+     */
+    send(channelId: Id, message: string, options?: RequestOptions): Promise<BotOwnerChatTurn>;
+}
+/** `/bot_facts` - what the responder knows, with optional validity dates. */
+export declare class BotFactsNamespace extends Resource {
+    list(params?: ListBotFactsParams, options?: RequestOptions): Promise<Paginated<BotFact>>;
+    get(id: Id, options?: RequestOptions): Promise<BotFact>;
+    /** @throws {OmsApiError} 400 when the channel's plugin is not the responder. */
+    create(input: CreateBotFactInput, options?: RequestOptions): Promise<BotFact>;
+    update(id: Id, input: UpdateBotFactInput, options?: RequestOptions): Promise<BotFact>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/** `/bot_sources` - pages the responder may read when a question calls for it. */
+export declare class BotSourcesNamespace extends Resource {
+    list(params?: ListBotSourcesParams, options?: RequestOptions): Promise<Paginated<BotSource>>;
+    get(id: Id, options?: RequestOptions): Promise<BotSource>;
+    create(input: CreateBotSourceInput, options?: RequestOptions): Promise<BotSource>;
+    update(id: Id, input: UpdateBotSourceInput, options?: RequestOptions): Promise<BotSource>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/** `/bot_responder_runs` - the responder's passes over the conversations, newest first. */
+export declare class BotResponderRunsNamespace extends Resource {
+    list(params?: ListBotResponderRunsParams, options?: RequestOptions): Promise<Paginated<BotResponderRun>>;
+    get(id: Id, options?: RequestOptions): Promise<BotResponderRun>;
+}
+export declare class BotsNamespace extends Resource {
+    readonly channels: BotChannelsNamespace;
+    readonly contacts: BotContactsNamespace;
+    readonly messages: BotMessagesNamespace;
+    readonly responders: BotRespondersNamespace;
+    readonly ownerChat: BotOwnerChatNamespace;
+    readonly facts: BotFactsNamespace;
+    readonly sources: BotSourcesNamespace;
+    readonly runs: BotResponderRunsNamespace;
+    constructor(http: ApiClient);
+}

package/dist/types/resources/content/news/feeds.d.ts

@@ -10,7 +10,9 @@ export declare const NEWS_FEED_MAX_RETENTION_DAYS = 3650;
 /**
  * A feed: a named set of {@link NewsSource}s and the {@link NewsItem}s they
  * produce. Several per account, unique by name; the oldest is the default
- * one a source lands in when it names no feed.
+ * one a source lands in when it names no feed. A feed may INCLUDE other
+ * feeds of yours (one level): listing its items also returns theirs, so
+ * sources can be grouped by kind ("Newspapers", "TV news") and reused.
  */
 export interface NewsFeed {
     readonly id: Id;
@@ -24,11 +26,14 @@ export interface NewsFeed {
     readonly retention_days: number;
     /** A disabled feed's sources are not polled. */
     readonly enabled: boolean;
+    /** Feeds of yours whose items this feed also lists (one level, no chaining). */
+    readonly included_feed_ids: Id[];
 }
-/** `GET /news_feeds/:id` adds two live counters. */
+/** `GET /news_feeds/:id` adds two live counters (this feed's own sources and items) and who includes it. */
 export interface NewsFeedDetail extends NewsFeed {
     readonly sources_count: number;
     readonly items_count: number;
+    readonly included_by_feed_ids: Id[];
 }
 /** Filter columns of `GET /news_feeds`, on top of {@link BASE_FILTER_COLUMNS}. */
 export declare const NEWS_FEED_FILTER_COLUMNS: readonly ["name", "enabled"];
@@ -39,6 +44,8 @@ export interface CreateNewsFeedInput {
     readonly description?: string | null;
     readonly retentionDays?: number;
     readonly enabled?: boolean;
+    /** REPLACES the list. Your own feeds only, the feed itself is dropped; anything else is a `400`. */
+    readonly includedFeedIds?: readonly Id[];
 }
 export type UpdateNewsFeedInput = Partial<CreateNewsFeedInput>;
 /** `/news_feeds` - your feeds. Needs `news:read` to read and `news:write` to change. */

package/dist/types/resources/content/news/index.d.ts

@@ -1,5 +1,6 @@
 /** The `news` namespace and everything under it. */
 import { type ApiClient, Resource } from "../../../http";
+import type { RequestOptions } from "../../../types";
 import { NewsFeedsNamespace } from "./feeds";
 import { NewsItemsNamespace } from "./items";
 import { NewsScriptsNamespace } from "./scripts";
@@ -8,6 +9,21 @@ export * from "./feeds";
 export * from "./items";
 export * from "./scripts";
 export * from "./sources";
+/** One feed a site declares or answers on a common path, already read and measured. */
+export interface DiscoveredFeed {
+    readonly url: string;
+    readonly kind: "rss" | "atom";
+    readonly title: string;
+    readonly items: number;
+    /** Entries carrying a date. */
+    readonly dated: number;
+}
+export interface NewsDiscovery {
+    readonly url: string;
+    readonly host: string;
+    readonly title: string;
+    readonly feeds: DiscoveredFeed[];
+}
 /**
  * The `news` namespace, reachable as `oms.content.news`: the ingestion side
  * of following the web.
@@ -33,4 +49,11 @@ export declare class NewsNamespace extends Resource {
     /** What the sources produced. Read plus delete. */
     readonly items: NewsItemsNamespace;
     constructor(http: ApiClient);
+    /**
+     * `GET /news/discover?url=` - the RSS/Atom feeds of a site: the ones its page declares
+     * and the common paths that answer, each fetched and measured. Cached for hours server-side.
+     *
+     * @throws {OmsApiError} 422 when the site cannot be read (the message says why).
+     */
+    discover(url: string, options?: RequestOptions): Promise<NewsDiscovery>;
 }

package/dist/types/resources/content/news/sources.d.ts

@@ -38,8 +38,20 @@ export interface NewsSource {
     readonly config: Record<string, Json>;
     /** The {@link NewsFeed} it belongs to. */
     readonly news_feed_id: Id;
-    /** Which {@link NewsScript} fetches this source. */
-    readonly news_script_id: Id;
+    /** Which {@link NewsScript} fetches this source, or `null` when a job does. */
+    readonly news_script_id: Id | null;
+    /**
+     * The cron job (`oms.cron.jobs`, with `output` items) that fetches this
+     * source instead of a script, and the schedule of that job the source owns:
+     * its `cron` comes from `poll_interval_minutes` and its `params` are the
+     * source's `config`. `null` for a script source.
+     */
+    readonly cron_job_id: Id | null;
+    readonly cron_schedule_id: Id | null;
+    /** The schedule's cron expression, for a job source. */
+    readonly cron: string | null;
+    /** Where the job runs, for a job source: `sandbox` or `full`. */
+    readonly runtime: "sandbox" | "full" | null;
     /** Minutes between polls. Validated `in: 5..1440`. */
     readonly poll_interval_minutes: number;
     /**
@@ -67,7 +79,7 @@ export interface NewsSource {
     readonly consecutive_failures: number;
 }
 /** Filter columns of `GET /news_sources`, on top of {@link BASE_FILTER_COLUMNS}. */
-export declare const NEWS_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "news_feed_id", "news_script_id"];
+export declare const NEWS_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "news_feed_id", "news_script_id", "cron_job_id"];
 /** Filters for {@link NewsSourcesNamespace.list}. */
 export interface ListNewsSourcesParams extends ListParams<(typeof NEWS_SOURCE_FILTER_COLUMNS)[number]> {
     /** Only healthy / only broken sources. Sent as `exact_search[health]`. */
@@ -78,6 +90,8 @@ export interface ListNewsSourcesParams extends ListParams<(typeof NEWS_SOURCE_FI
     readonly feedId?: Id;
     /** Every source driven by one script. */
     readonly scriptId?: Id;
+    /** Every source driven by one job. */
+    readonly jobId?: Id;
 }
 /** Arguments for {@link NewsSourcesNamespace.create}. */
 export interface CreateNewsSourceInput {
@@ -89,9 +103,17 @@ export interface CreateNewsSourceInput {
      * The script that fetches it. Must be a built-in or one of yours;
      * `script_visible_to_owner` rejects anything else with
      * `400 "News script is not accessible"` rather than a 404, so this also
-     * tells you the id exists. Do not use it as an existence oracle.
+     * tells you the id exists. Do not use it as an existence oracle. Give
+     * either this or `jobId`.
      */
-    readonly scriptId: Id;
+    readonly scriptId?: Id;
+    /**
+     * A cron job of yours with `output: { kind: "items" }` that fetches it
+     * instead of a script. The source gets a schedule of that job: the cron
+     * from `pollIntervalMinutes`, the `config` as the run params. `400` when
+     * the job has no items output.
+     */
+    readonly jobId?: Id;
     /** Whatever that script reads. Free-form; the API validates nothing in it. */
     readonly config?: Record<string, Json>;
     /** 5-1440. Defaults to 15 server-side. */
@@ -104,11 +126,36 @@ export interface CreateNewsSourceInput {
  *
  * One key wider than the create form: `cursor` is updatable and not creatable.
  */
+/** Arguments for {@link NewsSourcesNamespace.test}: a script, or a sandbox job (its config goes under the given one). */
+export interface TestNewsSourceInput {
+    readonly scriptId?: Id;
+    readonly jobId?: Id;
+    readonly config?: Record<string, Json>;
+}
+export interface NewsSourceTestItem {
+    readonly external_id: string;
+    readonly title: string;
+    readonly url: string | null;
+    readonly published_at: Timestamp | null;
+    readonly content: string | null;
+}
+/** What a dry run produced. `ok: false` carries the script's error. */
+export interface NewsSourceTest {
+    readonly ok: boolean;
+    readonly error?: string;
+    readonly items: NewsSourceTestItem[];
+    readonly count: number;
+    /** Items published in the last 30 days. */
+    readonly dated: number;
+    readonly logs: string[];
+}
 export interface UpdateNewsSourceInput {
     readonly name?: string;
     /** Moves the source (and nothing else: its items stay where they were written) to another of your feeds. */
     readonly newsFeedId?: Id;
+    /** Setting a script drops the job (and its schedule); setting a job drops the script. */
     readonly scriptId?: Id;
+    readonly jobId?: Id;
     /**
      * REPLACES the whole object; there is no merge. `assign_attributes` writes
      * the JSON column wholesale, so sending `{ url: "..." }` to a source that
@@ -235,5 +282,14 @@ export declare class NewsSourcesNamespace extends Resource {
      * @throws {OmsApiError} 404 `"Resource not found"` when the source is not
      *   yours.
      */
+    /**
+     * `POST /news_sources/test` - run a script with a config once, with no cursor
+     * and without creating anything, and get back the items it would produce.
+     * The dry run before creating or repairing a source.
+     *
+     * @throws {OmsApiError} 400 when the script is not a built-in or one of
+     *   yours; 502 when the runner is down.
+     */
+    test(input: TestNewsSourceInput, options?: RequestOptions): Promise<NewsSourceTest>;
     run(id: Id, options?: RequestOptions): Promise<NewsSourceRunAccepted>;
 }