@omelhorsite/sdk 0.3.0 → 0.4.0

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

@@ -0,0 +1,53 @@
+/** The `intel` namespace and everything under it. */
+import { type ApiClient, Resource } from "../../../http";
+import { IntelArticlesNamespace } from "./articles";
+import { IntelConfigNamespace } from "./config";
+import { IntelItemsNamespace } from "./items";
+import { IntelReportsNamespace } from "./reports";
+import { IntelScriptsNamespace } from "./scripts";
+import { IntelSourcesNamespace } from "./sources";
+import { IntelStatsNamespace } from "./stats";
+export * from "./articles";
+export * from "./config";
+export * from "./items";
+export * from "./reports";
+export * from "./scripts";
+export * from "./sources";
+export * from "./stats";
+export * from "./types";
+/**
+ * The `intel` namespace, reachable as `oms.content.intel`.
+ *
+ * A tour of the data model, because the names do not give it away:
+ *
+ * 1. a {@link IntelScript} knows HOW to fetch one kind of feed;
+ * 2. an {@link IntelSource} is that script plus its settings - a feed you
+ *    actually follow;
+ * 3. polling a source writes {@link IntelItem} rows: raw, unprocessed, one per
+ *    thing the feed published;
+ * 4. the analysis pipeline groups items into {@link IntelArticle} stories,
+ *    scores them against your {@link IntelConfig} rubric, enriches the
+ *    important ones and links related ones together;
+ * 5. {@link IntelReport} digests summarise a closed time window of stories.
+ *
+ * Only steps 1 and 2 are yours to write. Everything from step 3 on is produced
+ * by background jobs and is read-only over HTTP - a delete is the only mutation
+ * you get, and it is a hide, not an undo.
+ */
+export declare class IntelNamespace extends Resource {
+    /** Stories: the analysed, grouped, scored output. Read plus delete. */
+    readonly articles: IntelArticlesNamespace;
+    /** Generated digests over closed time windows. Read plus delete. */
+    readonly reports: IntelReportsNamespace;
+    /** The feeds you follow. Full CRUD, plus a manual run. */
+    readonly sources: IntelSourcesNamespace;
+    /** The fetchers. Full CRUD over yours; the built-ins are read-only. */
+    readonly scripts: IntelScriptsNamespace;
+    /** The raw material behind the stories. Read plus delete. */
+    readonly items: IntelItemsNamespace;
+    /** Your rubric, thresholds and prompt overrides. */
+    readonly config: IntelConfigNamespace;
+    /** Dashboard counters, in one expensive call. */
+    readonly stats: IntelStatsNamespace;
+    constructor(http: ApiClient);
+}

package/dist/types/resources/content/intel/items.d.ts

@@ -0,0 +1,91 @@
+/** Intel items: the raw material behind the stories. */
+import { Resource } from "../../../http";
+import type { ListParams } from "../../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../../types";
+/**
+ * A raw item, exactly as a script returned it.
+ *
+ * Written only by `Intel::FetchSourceJob`; over HTTP it is read-only plus a
+ * delete. Items are the substrate the stories are built from - the story never
+ * copies the body, it points here.
+ */
+export interface IntelItem {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Which source produced it. */
+    readonly intel_source_id: Id;
+    /**
+     * The script's own id for this item, unique per source. This is the
+     * de-duplication key: a second poll that returns the same `external_id` does
+     * not create a second row.
+     */
+    readonly external_id: string;
+    readonly title: string | null;
+    /** The body the script extracted. Can be large; a listing carries all of it. */
+    readonly content: string | null;
+    readonly url: string | null;
+    readonly author: string | null;
+    /** Publication time as the feed reported it, not as we saw it. */
+    readonly published_at: Timestamp | null;
+    /** When the poll that produced this item ran. Never null. */
+    readonly fetched_at: Timestamp;
+}
+/** Filter columns of `GET /intel_items`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_ITEM_FILTER_COLUMNS: readonly ["intel_source_id", "external_id", "title", "content", "url"];
+/** Filters for {@link IntelItemsNamespace.list}. */
+export interface ListIntelItemsParams extends ListParams<(typeof INTEL_ITEM_FILTER_COLUMNS)[number]> {
+    /** Only items produced by one source. Sent as `exact_search[intel_source_id]`. */
+    readonly sourceId?: Id;
+}
+/**
+ * `/intel_items` - the raw material.
+ *
+ * Read-only plus a delete: `creatable_by?` and `updatable_by?` are hard `false`
+ * and the route is `only: [:index, :show, :destroy]`. Items are written by
+ * `Intel::FetchSourceJob` and by nothing else.
+ *
+ * It is here because the stories only carry a citation stub
+ * ({@link IntelArticleSourceRef}) and this is the only way to read the body
+ * behind one.
+ */
+export declare class IntelItemsNamespace extends Resource {
+    /**
+     * `GET /intel_items` - raw items, newest first.
+     *
+     * **Heavy.** Every row carries {@link IntelItem.content} in full - the whole
+     * article text a script scraped - and there is no lighter view. The SDK
+     * defaults to a page of 25 for that reason; raising it is how you get a
+     * multi-megabyte response.
+     *
+     * Declared filters: `intel_source_id`, `external_id`, `title`, `content`,
+     * `url`, plus the inherited three. Note `processed_at` is NOT among them and
+     * is not on the payload either, so there is no way to list only the
+     * unprocessed items - {@link IntelStats.totals.pending_items} is the only
+     * window onto that backlog.
+     *
+     * The controller sets no ordering; the SDK sends `created_at:desc`.
+     */
+    list(params?: ListIntelItemsParams, options?: RequestOptions): Promise<Paginated<IntelItem>>;
+    /**
+     * `GET /intel_items/:id` - one raw item.
+     *
+     * There are no `:extended` extras, so this is the same shape a listing row
+     * has. Use it to expand one {@link IntelArticleSourceRef} without
+     * pulling a page of bodies.
+     *
+     * @throws {OmsApiError} 404 when the item is not yours.
+     */
+    get(id: Id, options?: RequestOptions): Promise<IntelItem>;
+    /**
+     * `DELETE /intel_items/:id`. `204`, empty body.
+     *
+     * Rarely what you want. The item's `external_id` uniqueness is what stops the
+     * next poll re-fetching it, so deleting one invites it straight back on the
+     * following run - and if the story built from it survives, you get a second
+     * citation of the same thing. Delete the SOURCE, or leave items alone.
+     *
+     * @throws {OmsApiError} 404 when the item is not yours.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}

package/dist/types/resources/content/intel/reports.d.ts

@@ -0,0 +1,108 @@
+/** Intel reports: generated digests over closed time windows. */
+import { Resource } from "../../../http";
+import type { ListParams } from "../../../listing";
+import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../../../types";
+import type { IntelArticleCategory, IntelReportKind } from "./types";
+/** A story as a report inlines it. Four keys, no summary and no body. */
+export interface IntelReportArticleRef {
+    readonly id: Id;
+    readonly title: string | null;
+    readonly importance: number;
+    readonly category: IntelArticleCategory | null;
+}
+/**
+ * A generated report over one closed time window.
+ *
+ * The index shape. `GET /intel_reports/:id` adds three keys - see
+ * {@link IntelReportDetail}.
+ *
+ * There is at most ONE report per `(user, kind, period_end)`: the migration
+ * puts a unique index on that triple precisely so a re-run of
+ * `GenerateReportJob` cannot mint a duplicate. Windows are the last CLOSED
+ * period, computed by `IntelReport.last_window`, so a `"day"` report covers
+ * yesterday and never the day in progress.
+ */
+export interface IntelReport {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Which window: see {@link INTEL_REPORT_KINDS}. */
+    readonly kind: IntelReportKind;
+    /** Title the model wrote. Nullable. */
+    readonly title: string | null;
+    /** Start of the window, inclusive. */
+    readonly period_start: Timestamp;
+    /** End of the window, exclusive. Also the sort key of the listing. */
+    readonly period_end: Timestamp;
+    /** LLM that wrote it, as configured at generation time. Nullable. */
+    readonly model: string | null;
+}
+/** `GET /intel_reports/:id` - the `:extended` view. */
+export interface IntelReportDetail extends IntelReport {
+    /** The report body, usually Markdown. `null` if generation failed halfway. */
+    readonly content: string | null;
+    /**
+     * Whatever the generator chose to record about the run. A free-form JSON
+     * object with no schema on either side, defaulting to `{}` - which is why it
+     * is typed as a bag rather than as fields. Read it defensively.
+     */
+    readonly stats: Record<string, Json> | null;
+    /** The stories the report covered, most important first. */
+    readonly articles: IntelReportArticleRef[];
+}
+/** Filter columns of `GET /intel_reports`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_REPORT_FILTER_COLUMNS: readonly ["kind"];
+/** Filters for {@link IntelReportsNamespace.list}. */
+export interface ListIntelReportsParams extends ListParams<(typeof INTEL_REPORT_FILTER_COLUMNS)[number]> {
+    /**
+     * Narrow to one window, e.g. `"day"`. Sent as `exact_search[kind]`, so it is
+     * equality rather than a prefix match - `"6h"` will not also match `"6hx"`.
+     *
+     * Passing it through {@link ListParams.search} instead would be a
+     * partial match and would work too; `kind` is on this controller's
+     * `search_params` allowlist. Equality is what you want.
+     */
+    readonly kind?: IntelReportKind;
+}
+/**
+ * `GET /intel_reports` - the generated digests.
+ *
+ * Read-only plus a delete, for the same reason as the stories: reports come
+ * from `Intel::GenerateReportJob`. There is no way to ask for one to be
+ * generated over HTTP.
+ */
+export declare class IntelReportsNamespace extends Resource {
+    /**
+     * `GET /intel_reports` - your reports, newest window first.
+     *
+     * `period_end DESC` is applied by the controller; as with the stories, a
+     * `order` of your own becomes the PRIMARY key and this becomes the
+     * tie-breaker.
+     *
+     * `kind` is the only declared filter beyond the inherited three. Use
+     * {@link ListIntelReportsParams.kind}, which sends it as an exact match.
+     *
+     * @throws {OmsApiError} 403 `"Intel access is restricted."` outside the
+     *   allowlist.
+     */
+    list(params?: ListIntelReportsParams, options?: RequestOptions): Promise<Paginated<IntelReport>>;
+    /**
+     * `GET /intel_reports/:id` - the report with its body and its stories.
+     *
+     * @throws {OmsApiError} 404 when the report is not yours.
+     */
+    get(id: Id, options?: RequestOptions): Promise<IntelReportDetail>;
+    /**
+     * `DELETE /intel_reports/:id`. `204`, empty body.
+     *
+     * The stories it cited are untouched - only the join rows go.
+     *
+     * A deleted report can come back: `GenerateReportJob` is keyed by the unique
+     * `(user, kind, period_end)` index, and deleting the row frees that key, so
+     * the next dispatcher pass over the same window will regenerate it. Delete a
+     * report to re-run it, not to suppress it.
+     *
+     * @throws {OmsApiError} 404 when the report is not yours.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}

package/dist/types/resources/content/intel/scripts.d.ts

@@ -0,0 +1,152 @@
+/** Intel scripts: the fetchers. */
+import { Resource } from "../../../http";
+import type { ListParams } from "../../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../../types";
+/** Largest script body the server will store. */
+export declare const INTEL_SCRIPT_MAX_CODE_BYTES: number;
+/**
+ * A TypeScript fetcher that knows how to pull items out of one kind of feed.
+ *
+ * Runs in the `intel-runner` sidecar, inside a V8 isolate with nothing but the
+ * injected `ctx`. Two populations share this table:
+ *
+ * - **built-ins** (`builtin: true`, `user_id: null`, `slug` set) are managed by
+ *   `Intel::BuiltinScripts`, visible to everyone, and immutable over HTTP;
+ * - **user scripts** (`builtin: false`, `user_id` set, `slug: null`) are yours.
+ *
+ * `viewable_by` is `builtin OR mine`, so a listing mixes the two. Check
+ * {@link builtin} before offering an edit affordance - see
+ * {@link IntelScriptsNamespace.update} for what happens if you do not.
+ */
+export interface IntelScript {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Up to 120 characters, whitespace-trimmed by the model. */
+    readonly name: string;
+    /** Stable handle, e.g. `"rss"`. Non-null for built-ins ONLY; always `null` for yours. */
+    readonly slug: string | null;
+    readonly description: string | null;
+    /** `true` for a platform script. Immutable, and not yours to delete. */
+    readonly builtin: boolean;
+    /** Owner. `null` exactly when {@link builtin} is `true`. */
+    readonly user_id: Id | null;
+    /**
+     * The source code - **only on the `:extended` view**.
+     *
+     * Only the `:extended` view carries `code`, so `get()`, `create()` and
+     * `update()` carry it and `list()` does not. That is a
+     * deliberate weight decision (a listing of 64 KiB bodies), not an oversight,
+     * and it is why this key is optional. A row from `list()` has it `undefined`;
+     * fetch the script by id when you actually need the body.
+     */
+    readonly code?: string;
+}
+/** Filter columns of `GET /intel_scripts`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_SCRIPT_FILTER_COLUMNS: readonly ["name", "builtin", "slug"];
+/** Filters for {@link IntelScriptsNamespace.list}. */
+export interface ListIntelScriptsParams extends ListParams<(typeof INTEL_SCRIPT_FILTER_COLUMNS)[number]> {
+    /**
+     * `true` for the platform scripts, `false` for yours. Omit for both - the
+     * listing scope is `builtin OR mine`, so both populations are mixed by
+     * default.
+     */
+    readonly builtin?: boolean;
+}
+/** Arguments for {@link IntelScriptsNamespace.create}. */
+export interface CreateIntelScriptInput {
+    /** Up to 120 characters. */
+    readonly name: string;
+    /** The body. Up to {@link INTEL_SCRIPT_MAX_CODE_BYTES}. */
+    readonly code: string;
+    readonly description?: string;
+}
+/** Arguments for {@link IntelScriptsNamespace.update}. */
+export interface UpdateIntelScriptInput {
+    readonly name?: string;
+    readonly code?: string;
+    readonly description?: string;
+}
+/**
+ * `/intel_scripts` - the fetchers. Full CRUD over YOUR scripts, read-only over
+ * the platform's.
+ */
+export declare class IntelScriptsNamespace extends Resource {
+    /**
+     * `GET /intel_scripts` - the built-ins plus yours, mixed.
+     *
+     * **No `code`.** The body is on the `:extended` view only, so every row here
+     * has `code: undefined`. See {@link IntelScript.code}.
+     *
+     * Declared filters: `name`, `builtin`, `slug`, plus the inherited three.
+     * The controller sets no ordering, so the SDK sends `created_at:desc`.
+     *
+     * @throws {OmsApiError} 403 outside the allowlist.
+     */
+    list(params?: ListIntelScriptsParams, options?: RequestOptions): Promise<Paginated<IntelScript>>;
+    /**
+     * `GET /intel_scripts/:id` - the script WITH its body.
+     *
+     * This is the only read that carries {@link IntelScript.code}. Works for a
+     * built-in too: they are visible to everyone, so this is how you read one
+     * before forking it.
+     *
+     * @throws {OmsApiError} 404 when the id is neither a built-in nor yours.
+     */
+    get(id: Id, options?: RequestOptions): Promise<IntelScript>;
+    /**
+     * `POST /intel_scripts` - saves a fetcher. `201`, with `code`.
+     *
+     * The controller transpiles the body in the `intel-runner` sidecar BEFORE
+     * saving, so a syntax error surfaces here rather than at the first poll:
+     * `400 "Invalid script: <the compiler's message>"`.
+     *
+     * **The check is best-effort and fails OPEN.** `check_script!` rescues
+     * `Intel::RunnerClient::Error` and returns `nil`, so when the runner is down
+     * or unreachable the script saves unchecked and a `201` means only "stored".
+     * There is nothing on the response that distinguishes a checked save from an
+     * unchecked one. Treat a successful create as "it parses, probably", and
+     * confirm with {@link IntelSourcesNamespace.run} on a throwaway source.
+     *
+     * The check is a transpile, not an execution: it proves the code parses, not
+     * that it fetches anything.
+     *
+     * The created script is always yours - `builtin` is not on `create_params`,
+     * so it cannot be set - and up to
+     * {@link INTEL_SCRIPT_MAX_CODE_BYTES} long.
+     *
+     * Not retried by default: a replay creates a second script.
+     */
+    create(input: CreateIntelScriptInput, options?: RequestOptions): Promise<IntelScript>;
+    /**
+     * `PATCH /intel_scripts/:id` - edits one of YOUR scripts. Answers with `code`.
+     *
+     * Same best-effort transpile check as {@link create}, and only when `code` is
+     * present in the body.
+     *
+     * **A built-in answers `401`, not `403`.** The body is
+     * `"You are not authorized to update this resource"` under a 401 status. That
+     * is an authorisation refusal wearing an authentication status code: do NOT
+     * let a generic 401 handler log the user out over it. Check
+     * {@link IntelScript.builtin} first and fork instead of editing.
+     *
+     * A live edit takes effect on the next poll of every source using this
+     * script; there is no versioning and no rollback.
+     *
+     * @throws {OmsApiError} 404 when the id is not visible to you; 401 for a
+     *   built-in; 400 for a syntax error or an over-long body.
+     */
+    update(id: Id, input: UpdateIntelScriptInput, options?: RequestOptions): Promise<IntelScript>;
+    /**
+     * `DELETE /intel_scripts/:id`. `204`, empty body.
+     *
+     * Refuses while any source still uses it, with
+     * `400 "Cannot delete record because dependent intel sources exist"`. Delete
+     * or repoint the sources first - {@link IntelSourcesNamespace.list} with
+     * `scriptId` finds them in one call.
+     *
+     * A built-in answers `401` with `"You are not authorized to destroy this
+     * resource"`, for the reason spelled out on {@link update}.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}

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

@@ -0,0 +1,236 @@
+/** Intel sources: the feeds you follow. */
+import { Resource } from "../../../http";
+import type { ListParams } from "../../../listing";
+import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../../../types";
+/** The three values a source's health can take. */
+export declare const INTEL_SOURCE_HEALTHS: readonly ["unknown", "ok", "error"];
+/** Health of a source's last run. `"unknown"` until it has ever run. */
+export type IntelSourceHealth = (typeof INTEL_SOURCE_HEALTHS)[number];
+/**
+ * Consecutive failures after which a source flips `enabled` to `false` by
+ * itself.
+ *
+ * Nothing turns it back on: a source that hit this stays off until someone
+ * `update()`s `enabled` back to `true`. That is what
+ * {@link IntelSource.consecutive_failures} is for - watch it, do not wait for
+ * an alert.
+ */
+export declare const INTEL_SOURCE_DISABLE_AFTER_FAILURES = 20;
+/**
+ * A configured feed: a script plus the settings that script needs.
+ *
+ * A source is polled by `PollDispatcherJob` once every
+ * {@link poll_interval_minutes}, and each poll writes {@link IntelItem} rows
+ * that the analysis pipeline later turns into stories.
+ */
+export interface IntelSource {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Up to 200 characters, whitespace-trimmed by the model, unique per user. */
+    readonly name: string;
+    /**
+     * The script's own settings - a URL, a channel, a CSS selector. There is no
+     * schema: the backend permits `config: {}`, meaning an arbitrary object, and
+     * the SCRIPT decides what it reads out of it. What belongs in here is
+     * documented by the script, not by this API.
+     */
+    readonly config: Record<string, Json>;
+    /** Which {@link IntelScript} fetches this source. */
+    readonly intel_script_id: Id;
+    /** Minutes between polls. Validated `in: 5..1440`. */
+    readonly poll_interval_minutes: number;
+    /**
+     * Whether the dispatcher will poll it.
+     *
+     * Can flip to `false` WITHOUT anyone asking: see
+     * {@link INTEL_SOURCE_DISABLE_AFTER_FAILURES}.
+     */
+    readonly enabled: boolean;
+    /**
+     * Incremental cursor the script returned last time - a timestamp, an etag, a
+     * last-seen id, whatever that script uses. Opaque to everything but the
+     * script. Writable, so clearing it is how you force a full re-fetch.
+     */
+    readonly cursor: string | null;
+    /** Result of the last run. `"unknown"` until it has run once. */
+    readonly health: IntelSourceHealth;
+    /** Failure message from the last failed run, truncated to 1000 characters. */
+    readonly last_error: string | null;
+    /** When the source last ran, successfully or not. */
+    readonly last_run_at: Timestamp | null;
+    /** When it last SUCCEEDED. A gap between the two is the thing to alert on. */
+    readonly last_success_at: Timestamp | null;
+    /** Reset to 0 on any success. See {@link INTEL_SOURCE_DISABLE_AFTER_FAILURES}. */
+    readonly consecutive_failures: number;
+}
+/** Filter columns of `GET /intel_sources`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "intel_script_id"];
+/** Filters for {@link IntelSourcesNamespace.list}. */
+export interface ListIntelSourcesParams extends ListParams<(typeof INTEL_SOURCE_FILTER_COLUMNS)[number]> {
+    /** Only healthy / only broken feeds. Sent as `exact_search[health]`. */
+    readonly health?: IntelSourceHealth;
+    /** Only enabled, or only the ones that switched themselves off. */
+    readonly enabled?: boolean;
+    /** Every source driven by one script. */
+    readonly scriptId?: Id;
+}
+/** Arguments for {@link IntelSourcesNamespace.create}. */
+export interface CreateIntelSourceInput {
+    /** Up to 200 characters, and unique among YOUR sources - a clash is a 400. */
+    readonly name: string;
+    /**
+     * The script that fetches it. Must be a built-in or one of yours;
+     * `script_visible_to_owner` rejects anything else with
+     * `400 "Intel script is not accessible"` rather than a 404, so this also
+     * tells you the id exists. Do not use it as an existence oracle.
+     */
+    readonly intelScriptId: 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. */
+    readonly pollIntervalMinutes?: number;
+    /** Defaults to `true`. Create it disabled if you want to configure first. */
+    readonly enabled?: boolean;
+}
+/**
+ * Arguments for {@link IntelSourcesNamespace.update}.
+ *
+ * One key wider than the create form: `cursor` is updatable and not creatable.
+ */
+export interface UpdateIntelSourceInput {
+    readonly name?: string;
+    readonly intelScriptId?: Id;
+    /**
+     * REPLACES the whole object; there is no merge. `assign_attributes` writes
+     * the JSON column wholesale, so sending `{ url: "..." }` to a source that
+     * also had a `selector` drops the selector. Read the source, spread, write.
+     */
+    readonly config?: Record<string, Json>;
+    readonly pollIntervalMinutes?: number;
+    /** Set back to `true` to revive a source that disabled itself. */
+    readonly enabled?: boolean;
+    /**
+     * The incremental cursor. Set it to `null` to force the next poll to start
+     * from the beginning - which for most scripts means re-fetching everything.
+     *
+     * `null` here is a JSON body `null`, not the query-string sentinel: bodies
+     * never carry `\b`.
+     */
+    readonly cursor?: string | null;
+}
+/** What `POST /intel_sources/:id/run` answers with. The whole body. */
+export interface IntelSourceRunAccepted {
+    /** Always `true`. The job was enqueued; nothing has been fetched yet. */
+    readonly queued: boolean;
+}
+/**
+ * `/intel_sources` - the feeds you have configured. Full CRUD, plus a manual
+ * run.
+ */
+export declare class IntelSourcesNamespace extends Resource {
+    /**
+     * `GET /intel_sources` - your feeds.
+     *
+     * Declared filters: `name`, `health`, `enabled`, `intel_script_id`, plus the
+     * inherited `id`, `created_at`, `updated_at`. The controller sets NO ordering
+     * of its own, so a listing with no `order` is in whatever order Postgres
+     * returns rows - which is not stable across pages. The SDK therefore sends
+     * `created_at:desc` unless you say otherwise.
+     *
+     * A good health check in one call: `list({ health: "error" })`.
+     *
+     * @throws {OmsApiError} 403 outside the allowlist.
+     */
+    list(params?: ListIntelSourcesParams, options?: RequestOptions): Promise<Paginated<IntelSource>>;
+    /**
+     * `GET /intel_sources/:id`.
+     *
+     * There are no `:extended` extras, so this is exactly the shape a listing
+     * row has. Fetching one adds nothing but a round trip;
+     * prefer finding it in {@link list} when you already have the page.
+     *
+     * @throws {OmsApiError} 404 when the source is not yours.
+     */
+    get(id: Id, options?: RequestOptions): Promise<IntelSource>;
+    /**
+     * `POST /intel_sources` - configures a feed. `201`.
+     *
+     * The source starts `health: "unknown"` and is not polled immediately: the
+     * dispatcher picks it up on its next pass, or you can force it with
+     * {@link run}.
+     *
+     * Three ways this fails with a 400 and a bare-string body:
+     *
+     * - `"Name has already been taken"` - names are unique per user;
+     * - `"Intel script is not accessible"` - the script is neither a built-in nor
+     *   yours. This is a 400 rather than a 404, so it does not tell you whether
+     *   the id exists;
+     * - `"Source limit reached (N)"` - you are at
+     *   {@link IntelConfig.max_sources}. Raise it with
+     *   {@link IntelConfigNamespace.update} if the ceiling is yours to raise.
+     *
+     * Not retried by default: a replayed `POST` after a lost response would fail
+     * the uniqueness check rather than duplicate the row, but it would report
+     * that failure as if the first attempt had never worked.
+     */
+    create(input: CreateIntelSourceInput, options?: RequestOptions): Promise<IntelSource>;
+    /**
+     * `PATCH /intel_sources/:id`.
+     *
+     * Note what is NOT writable: `health`, `last_error`, `last_run_at`,
+     * `last_success_at` and `consecutive_failures` are not on `update_params`, so
+     * you cannot clear a source's failure history by hand. Only a successful run
+     * resets it (`register_success!`). Re-enabling a source that disabled itself
+     * therefore leaves `consecutive_failures` at 20 until the next success - do
+     * not read that field as "currently failing".
+     *
+     * {@link UpdateIntelSourceInput.config} replaces the whole object.
+     *
+     * @throws {OmsApiError} 404 when the source is not yours; 400 with the
+     *   validation sentence otherwise.
+     */
+    update(id: Id, input: UpdateIntelSourceInput, options?: RequestOptions): Promise<IntelSource>;
+    /**
+     * `DELETE /intel_sources/:id`. `204`, empty body.
+     *
+     * Destructive well beyond the row: `has_many :intel_items, dependent:
+     * :destroy` takes every raw item this source ever produced, and the stories
+     * built from them lose their citations
+     * ({@link IntelArticleDetail.sources} shrinks, {@link IntelArticle.n_sources}
+     * with it) while the stories themselves stay. Disabling is almost always what
+     * you meant: `update(id, { enabled: false })`.
+     *
+     * @throws {OmsApiError} 404 when the source is not yours.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /intel_sources/:id/run` - polls the source now instead of waiting
+     * for its interval. `202 {"queued":true}`.
+     *
+     * **It enqueues; it does not fetch.** The answer arrives before anything has
+     * happened, and it says nothing about whether the poll will succeed. To see
+     * the outcome, re-read the source and watch {@link IntelSource.last_run_at},
+     * {@link IntelSource.health} and {@link IntelSource.last_error}. There is no
+     * job id and nothing to wait on.
+     *
+     * Three sharp edges:
+     *
+     * - it runs a source even when {@link IntelSource.enabled} is `false`. The
+     *   action does not look at the flag, so this is also how you test a feed you
+     *   have deliberately switched off;
+     * - it is authorised by VISIBILITY only. The action does its own `find_by`
+     *   inside `viewable_by` and never calls `updatable_by?` - which happens to
+     *   be the same set here, since sources are only ever visible to their owner;
+     * - it has **no bucket of its own**. It rides the general 600-per-minute
+     *   ceiling, so a loop can enqueue hundreds of `FetchSourceJob`s into the
+     *   `syncs` queue in seconds and starve everything else on it. Call it on a
+     *   user gesture; never in a poll loop.
+     *
+     * Not retried by default: a replay enqueues a second fetch.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"` when the source is not
+     *   yours.
+     */
+    run(id: Id, options?: RequestOptions): Promise<IntelSourceRunAccepted>;
+}