@omelhorsite/sdk 0.3.0 → 0.4.0

package/dist/types/resources/content/feedbacks.d.ts

@@ -0,0 +1,263 @@
+/** The feedback box and its admin queue. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { FileOutput, Id, Paginated, RequestOptions, Timestamp } from "../../types";
+/** Filter columns of `GET /feedbacks`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const FEEDBACK_FILTER_COLUMNS: readonly ["status", "user_id"];
+/** Filters for {@link FeedbacksNamespace.list}. */
+export type ListFeedbacksParams = ListParams<(typeof FEEDBACK_FILTER_COLUMNS)[number]>;
+/**
+ * Primary key of a feedback report. A STRING, not an integer: `feedbacks` is
+ * one of the tables that moved to opaque random ids, and it is the only one in
+ * this file that did.
+ */
+export type FeedbackId = Id;
+/** Triage state of a report. */
+export declare const FEEDBACK_STATUSES: readonly ["new", "read", "archived"];
+/** One of {@link FEEDBACK_STATUSES}. */
+export type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];
+/** Longest report the endpoint accepts, in BYTES. */
+export declare const FEEDBACK_CONTENT_MAX_BYTES = 5000;
+/** How many attachments survive one submission. Mirrors `MAX_ATTACHMENTS_COUNT`. */
+export declare const FEEDBACK_MAX_ATTACHMENTS = 6;
+/** Combined decoded size of the attachments that get stored. 10 MiB. */
+export declare const FEEDBACK_MAX_ATTACHMENTS_TOTAL_BYTES: number;
+/** Longest single `data:` URL the attacher will decode. 15 MiB of base64. */
+export declare const FEEDBACK_MAX_ATTACHMENT_DATA_URL_BYTES: number;
+/** Anonymous submissions allowed per hour per IP, before rack-attack answers 429. */
+export declare const FEEDBACK_CREATE_RATE_LIMIT_PER_HOUR = 5;
+/** How long an identical report from the same IP is folded into the first one. */
+export declare const FEEDBACK_DUPLICATE_WINDOW_MS: number;
+/** A stored attachment, as it appears on a report. Admin-visible only. */
+export interface FeedbackAttachment {
+    /** ActiveStorage blob id. An INTEGER, and the segment `attachmentUrl` needs. */
+    readonly blob_id: number;
+    readonly filename: string;
+    readonly content_type: string;
+    readonly byte_size: number;
+}
+/** The submitter, when they were signed in. Carries their email, so admin-only. */
+export interface FeedbackSubmitter {
+    readonly id: Id;
+    readonly handle: string;
+    readonly name: string;
+    readonly email: string;
+}
+/**
+ * A feedback report, as an admin reads it.
+ *
+ * Nobody else ever sees this shape: `viewable_by` is `user&.admin? ? all : none`,
+ * so a non-admin's listing is empty and a non-admin's `show` is a 404. The
+ * submitter cannot read back what they sent - {@link FeedbacksNamespace.create}
+ * answers with an id and nothing else.
+ */
+export interface Feedback {
+    readonly id: FeedbackId;
+    /** What the person wrote. Up to {@link FEEDBACK_CONTENT_MAX_BYTES} bytes. */
+    readonly content: string;
+    readonly status: FeedbackStatus;
+    /**
+     * The three context keys the controller keeps (`path`, `source`,
+     * `user_agent`); everything else the client sent is dropped before the row
+     * is written. `{}` when nothing was sent.
+     */
+    readonly context: Record<string, string>;
+    /** The account that submitted it, or `null` for an anonymous report. */
+    readonly user_id: Id | null;
+    /** Reply address for an anonymous report, or `null`. */
+    readonly email: string | null;
+    /**
+     * ISO country resolved from the submitter's IP by `FeedbackIntakeJob`.
+     *
+     * Written by a background job AFTER the response, so it is `null` on a row
+     * read immediately after submission and fills in a moment later. Same for
+     * {@link device_name}.
+     */
+    readonly country: string | null;
+    /** Device name parsed out of the user agent, by the same background job. */
+    readonly device_name: string | null;
+    /** Expanded account, or `null` when the report was anonymous. */
+    readonly user: FeedbackSubmitter | null;
+    /** Screenshots, in submission order. Empty when none survived the filters. */
+    readonly attachments: FeedbackAttachment[];
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+}
+/** One screenshot, sent inline as a `data:` URL rather than as multipart. */
+export interface FeedbackAttachmentInput {
+    /**
+     * A full `data:<mime>;base64,<payload>` URL. Anything that does not match
+     * that exact regex - a bare base64 string, a `data:` URL that is not base64 -
+     * is skipped in silence.
+     */
+    readonly data_url: string;
+    /** Name to store. Sanitised server-side; defaults to `feedback-<id>-attachment-<n>.<ext>`. */
+    readonly filename?: string;
+}
+/** Arguments for {@link FeedbacksNamespace.create}. */
+export interface CreateFeedbackInput {
+    /**
+     * The report. Trimmed, and rejected when blank
+     * (`400 "Feedback can't be empty"`) or over
+     * {@link FEEDBACK_CONTENT_MAX_BYTES} BYTES - bytes, not characters, so
+     * accented text runs out sooner than the number suggests
+     * (`400 "Feedback is too long"`).
+     */
+    readonly content: string;
+    /**
+     * Reply address. Only meaningful for an anonymous report: a signed-in
+     * submitter is linked by `user_id` and their account email is what the admin
+     * sees. Validated against `URI::MailTo::EMAIL_REGEXP` when present.
+     */
+    readonly email?: string;
+    /**
+     * Where the report came from. Only `path`, `source` and `user_agent`
+     * survive; every other key is dropped without an error.
+     */
+    readonly context?: {
+        readonly path?: string;
+        readonly source?: string;
+        readonly user_agent?: string;
+    };
+    /**
+     * Screenshots, at most {@link FEEDBACK_MAX_ATTACHMENTS}.
+     *
+     * Every rule here fails SILENTLY - the attacher logs and moves on, and the
+     * submission still answers `201`. An attachment is dropped when it is not a
+     * base64 `data:` URL, when its MIME type is not `image/*`, when the URL is
+     * over {@link FEEDBACK_MAX_ATTACHMENT_DATA_URL_BYTES}, or when the running
+     * decoded total passes {@link FEEDBACK_MAX_ATTACHMENTS_TOTAL_BYTES} (which
+     * drops that one AND every one after it). Anything past the sixth is
+     * discarded before the loop even starts. So do not treat a `201` as proof
+     * the screenshots arrived; only an admin reading {@link Feedback.attachments}
+     * can confirm that.
+     *
+     * Base64 is roughly 4/3 the size of the bytes, and the whole thing travels
+     * inside one JSON body: production sits behind Cloudflare's ~100 MB request
+     * cap, which rejects an oversized body with a `413` of its own before Rails
+     * sees it.
+     */
+    readonly attachments?: readonly FeedbackAttachmentInput[];
+    /**
+     * Cloudflare Turnstile token. REQUIRED for an anonymous submission and
+     * ignored for a signed-in one.
+     *
+     * Get the site key from {@link SiteConfigNamespace.get} first. Missing is
+     * `400 "Captcha token missing"`; present but not verifying is
+     * `403 "Captcha verification failed"`. A token is single-use at Cloudflare,
+     * so it cannot be replayed - which also means an SDK-level retry of a failed
+     * anonymous submission needs a FRESH token, not the same one.
+     */
+    readonly cf_turnstile_token?: string;
+}
+/**
+ * The `feedbacks` namespace: the site's feedback box, plus its admin queue.
+ *
+ * Two audiences and one route table. {@link create} is the only thing a normal
+ * caller can reach, and it is deliberately anonymous-friendly; everything else
+ * is `before_action :require_admin!` and answers `401` with a `null` body to
+ * anyone else.
+ */
+export declare class FeedbacksNamespace extends Resource {
+    /**
+     * `POST /feedbacks` - submits a report. `201` with `{"id": "..."}`, which is
+     * unwrapped here to the id string.
+     *
+     * The response carries the id ALONE. There is no way to read the row back
+     * without being an admin, so the id is only useful for correlating with a
+     * support conversation.
+     *
+     * ## The ceilings, and why they are there
+     *
+     * This route has the only dedicated rack-attack bucket in this file:
+     * **{@link FEEDBACK_CREATE_RATE_LIMIT_PER_HOUR} per hour, keyed on the IP**,
+     * added after a bot pushed roughly 200 admin notification emails through it
+     * in a single burst. It is keyed on the IP for EVERY caller, signed in or
+     * not, so a shared egress address (an office, a mobile carrier's NAT, a
+     * corporate VPN) shares the budget. Over it, `429` with
+     * `{"error":"rate_limited"}`, which arrives here as an {@link OmsQuotaError}.
+     *
+     * On top of that the controller de-duplicates: the same `content` from the
+     * same IP inside {@link FEEDBACK_DUPLICATE_WINDOW_MS} returns the id of the
+     * EXISTING row with a `201` and writes nothing, attaches nothing and sends
+     * no email. So a double-submitted form is harmless, and a retry inside the
+     * window is genuinely idempotent - but note the flip side: a user who
+     * legitimately sends the same short sentence twice in three minutes gets one
+     * report, and the second submission's ATTACHMENTS are silently lost, because
+     * the de-duplication branch returns before the attacher runs.
+     *
+     * ## What happens after the 201
+     *
+     * `FeedbackIntakeJob` runs on the queue: geo-locates the IP into
+     * {@link Feedback.country}, parses the user agent into
+     * {@link Feedback.device_name}, sends one coalesced email to every admin,
+     * and fires a Discord alert. None of it blocks the response, and none of it
+     * can fail the submission.
+     *
+     * The submitter's IP and user agent are stored on the row regardless of
+     * whether they signed in. Say so in your UI if that matters.
+     *
+     * @throws {OmsApiError} 400 `"Feedback can't be empty"` / `"Feedback is too long"`
+     *   / `"Captcha token missing"`; 403 `"Captcha verification failed"`.
+     * @throws {OmsQuotaError} 429 once the per-IP hourly budget is spent.
+     */
+    create(input: CreateFeedbackInput, options?: RequestOptions): Promise<FeedbackId>;
+    /**
+     * `GET /feedbacks` - the admin triage queue. **Admin only.**
+     *
+     * A non-admin is stopped by `before_action :require_admin!` with a `401`
+     * whose body is `null` - no message to show the user, so write your own.
+     * `Feedback.viewable_by` collapsing to `none` for a non-admin is the second
+     * layer behind that, not the one you will hit.
+     *
+     * Filterable on `status` and `user_id`, plus the three defaults (`id`,
+     * `created_at`, `updated_at`). Any other key is `400`.
+     *
+     * The scope is ordered `created_at DESC` before the DSL runs, and
+     * `modifiers[order]` uses `reorder`, so passing {@link ListParams.order}
+     * REPLACES that default rather than refining it.
+     */
+    list(params?: ListFeedbacksParams, options?: RequestOptions): Promise<Paginated<Feedback>>;
+    /**
+     * `GET /feedbacks/:id` - one report in full. **Admin only**; anybody else
+     * gets `401` with a `null` body.
+     */
+    get(id: FeedbackId, options?: RequestOptions): Promise<Feedback>;
+    /**
+     * `PATCH /feedbacks/:id` - moves a report through triage. **Admin only.**
+     *
+     * `status` is the only writable field: `update_params :status` is the whole
+     * allowlist, so `content` and `email` cannot be edited, and a value outside
+     * {@link FEEDBACK_STATUSES} is rejected by a `before_update` hook with
+     * `400 "Invalid status"` before the model is touched.
+     */
+    setStatus(id: FeedbackId, status: FeedbackStatus, options?: RequestOptions): Promise<Feedback>;
+    /**
+     * `DELETE /feedbacks/:id` - permanent, attachments included. `204`.
+     * **Admin only.**
+     */
+    destroy(id: FeedbackId, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /feedbacks/:id/attachment/:blobId` - downloads one screenshot.
+     * **Admin only.**
+     *
+     * The endpoint answers a `302` into object storage, not the bytes, so this
+     * follows the redirect and buffers the result. That works in Bun and in
+     * React Native; in a BROWSER it is the same CORS trap `account.picture`
+     * documents - the redirect target does not accept a credentialed
+     * cross-origin request, and the fetch fails after the 302. A web client
+     * should point an `<img>` at {@link attachmentUrl} instead and let the
+     * browser follow the redirect without credentials.
+     */
+    attachment(id: FeedbackId, blobId: number, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * The absolute URL of an attachment, for an `<img src>` or an `<a href>`.
+     *
+     * Builds the string and makes no request, so it carries whatever credential
+     * the BROWSER attaches - which for a cookie session on the API's own origin
+     * is the session cookie, and for a bearer-token client is nothing at all. A
+     * token-authenticated host has to fetch the bytes with {@link attachment}
+     * instead; there is no query-string credential this SDK will mint for you.
+     */
+    attachmentUrl(id: FeedbackId, blobId: number): string;
+}

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

@@ -0,0 +1,52 @@
+/** The `content` namespace and everything under it. */
+import { type ApiClient, Resource } from "../../http";
+import { AnalysisNamespace } from "./analysis";
+import { BlogsNamespace } from "./blogs";
+import { FeedbacksNamespace } from "./feedbacks";
+import { IntelNamespace } from "./intel/index";
+import { JokesNamespace } from "./jokes";
+import { NotificationsNamespace } from "./notifications";
+import { ServiceUsagesNamespace } from "./serviceUsages";
+import { ServicesStatusNamespace } from "./servicesStatus";
+import { SiteConfigNamespace } from "./siteConfig";
+import { SpaceInvadersNamespace } from "./spaceInvaders";
+export * from "./analysis";
+export * from "./blogs";
+export * from "./feedbacks";
+export * from "./intel/index";
+export * from "./jokes";
+export * from "./notifications";
+export * from "./serviceUsages";
+export * from "./servicesStatus";
+export * from "./siteConfig";
+export * from "./spaceInvaders";
+/**
+ * The `content` namespace, reachable as `oms.content`.
+ *
+ * An umbrella over ten unrelated corners of the API. Nothing is shared between
+ * them, so mount the sub-namespaces directly if a flatter surface reads better
+ * - each one is exported on its own.
+ */
+export declare class ContentNamespace extends Resource {
+    /** Blogs, blog posts and subscriptions. `.posts` hangs off it. */
+    readonly blogs: BlogsNamespace;
+    /** The notification inbox. HTTP half only; the cable pushes the rest. */
+    readonly notifications: NotificationsNamespace;
+    /** The feedback box, and its admin queue. */
+    readonly feedbacks: FeedbacksNamespace;
+    /** The joke table behind the loading screens. */
+    readonly jokes: JokesNamespace;
+    /** The public config blob a client reads before it has a credential. */
+    readonly config: SiteConfigNamespace;
+    /** The status page: live probes and the 90-day uptime report. */
+    readonly status: ServicesStatusNamespace;
+    /** Per-user "which parts of the site do you open" counters. */
+    readonly serviceUsages: ServiceUsagesNamespace;
+    /** Two admin storage reports. */
+    readonly analysis: AnalysisNamespace;
+    /** The Space Invaders leaderboard. */
+    readonly spaceInvaders: SpaceInvadersNamespace;
+    /** Intel: articles, reports, sources, scripts, items, config and stats. See {@link IntelNamespace}. */
+    readonly intel: IntelNamespace;
+    constructor(http: ApiClient);
+}

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

@@ -0,0 +1,230 @@
+/** Intel stories: the analysed, grouped, scored output. */
+import { Resource } from "../../../http";
+import type { ListParams } from "../../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../../types";
+import type { IntelArticleCategory, IntelReportKind } from "./types";
+/**
+ * A story: several raw items about the same event, grouped, scored and
+ * categorised by the analysis pipeline.
+ *
+ * This is the shape an INDEX row has. `GET /intel_articles/:id` renders
+ * `:extended`, which is this plus four more keys - see
+ * {@link IntelArticleDetail}. The detail is always a superset, never a
+ * different record.
+ */
+export interface IntelArticle {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Headline the model wrote. Nullable: the column has no `NOT NULL`. */
+    readonly title: string | null;
+    /** One-paragraph summary. Nullable for the same reason. */
+    readonly summary: string | null;
+    /**
+     * 0-10, validated `only_integer, in: 0..10`. The buckets the dashboard uses
+     * are in {@link IntelStats.by_importance} and they are NOT evenly spaced:
+     * >=9 critical, 7-8 high, 5-6 medium, 3-4 low, <3 noise.
+     */
+    readonly importance: number;
+    /** See {@link IntelArticleCategory}. `null` when unclassified. */
+    readonly category: IntelArticleCategory | null;
+    /**
+     * Free-form tags. The column defaults to `[]`, but it is nullable, so a row
+     * written before the default landed can still hand you `null`. Do not map
+     * over it without a guard.
+     */
+    readonly tags: string[] | null;
+    /**
+     * The `og:image` of one of the story's sources, stored RAW and uncompressed
+     * - it points at whatever news site published it, not at this API. Render it
+     * through {@link intelArticleImageUrl} rather than directly; that helper
+     * explains the trade it makes.
+     */
+    readonly image_url: string | null;
+    /**
+     * Whether the web-search enrichment pass has run on this story.
+     *
+     * `false` is not a failure, it is a queue position: `AnalyzeUserJob` enriches
+     * at most three stories per run, only those at or above
+     * {@link IntelConfig.enrich_min_importance}, and only while
+     * {@link IntelConfig.web_search} is on. A low-importance story stays `false`
+     * for ever, by design.
+     */
+    readonly enriched: boolean;
+    /** When the story was first built. */
+    readonly first_seen_at: Timestamp;
+    /** Touched every time a new item joins the story. This is the "recency" clock. */
+    readonly last_seen_at: Timestamp;
+    /**
+     * How many raw items back this story.
+     *
+     * Costs one COUNT query per row on the listing. A page of 500 stories is
+     * 500 extra queries. This is the reason to keep `pageSize` modest on
+     * {@link IntelArticlesNamespace.list}.
+     */
+    readonly n_sources: number;
+}
+/** One raw item cited by a story, as `:extended` inlines it. */
+export interface IntelArticleSourceRef {
+    /** Id of the {@link IntelItem}. Fetch the full row with `items.get(id)`. */
+    readonly id: Id;
+    /** Name of the {@link IntelSource} the item came from, or `null` if it was deleted. */
+    readonly source_name: string | null;
+    readonly title: string | null;
+    readonly url: string | null;
+    readonly published_at: Timestamp | null;
+}
+/**
+ * A story related to this one, as `:extended` inlines it.
+ *
+ * "Related" is not "duplicate": duplicates are merged during dedup and never
+ * become two rows. `IntelArticleLink` is an undirected edge between two
+ * DISTINCT stories, which is why {@link relation} is one label describing the
+ * pair rather than a direction.
+ */
+export interface IntelRelatedArticleRef {
+    readonly id: Id;
+    readonly title: string | null;
+    readonly importance: number;
+    readonly category: IntelArticleCategory | null;
+    /** Free text the model wrote for the edge, e.g. a pattern name. Nullable. */
+    readonly relation: string | null;
+}
+/** A report this story appears in, as `:extended` inlines it. Newest period first. */
+export interface IntelArticleReportRef {
+    readonly id: Id;
+    readonly kind: IntelReportKind;
+    readonly title: string | null;
+    readonly period_end: Timestamp;
+}
+/**
+ * `GET /intel_articles/:id` - the `:extended` view.
+ *
+ * Four keys the listing does not carry, and all four are joins run inline:
+ * `sources` walks `intel_items`, `related` walks the link table in
+ * BOTH directions, `reports` orders the report join by `period_end`. There is
+ * no paging on any of them, so a story that has been running for a week can
+ * inline a lot of rows.
+ */
+export interface IntelArticleDetail extends IntelArticle {
+    /** The long body. `null` until the enrichment pass writes one. */
+    readonly details: string | null;
+    /** Every raw item behind the story. Length matches {@link IntelArticle.n_sources}. */
+    readonly sources: IntelArticleSourceRef[];
+    /** Stories linked to this one. `[]` when the linker found nothing. */
+    readonly related: IntelRelatedArticleRef[];
+    /** Reports that cited this story, newest period first. */
+    readonly reports: IntelArticleReportRef[];
+}
+/** Filter columns of `GET /intel_articles`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_ARTICLE_FILTER_COLUMNS: readonly ["title", "summary", "category", "importance", "enriched"];
+/** Filters for {@link IntelArticlesNamespace.list}. */
+export interface ListIntelArticlesParams extends ListParams<(typeof INTEL_ARTICLE_FILTER_COLUMNS)[number]> {
+    /**
+     * Free-text search over `title`, `summary` AND `details`.
+     *
+     * A TOP-LEVEL parameter, not a `search` key: the controller reads
+     * `params[:q]` itself, which is why it can reach `details` (a column that is
+     * not in `search_params` at all) and why an unknown-filter 400 cannot
+     * happen for it.
+     *
+     * Three ways it differs from {@link ListParams.search}:
+     *
+     * - it is **accent-SENSITIVE**. The controller does `LOWER(col) LIKE
+     *   LOWER(term)`, with no unaccenting, while the list DSL's `search` strips
+     *   accents on both sides. `"policia"` will not find `"polícia"` here.
+     * - `%` and `_` in your term are **not escaped**. The controller wraps the
+     *   term as `"%#{q}%"` and binds it, so a term containing `%` is a wildcard,
+     *   not a literal percent sign. Not an injection - it is a bound parameter -
+     *   but a surprise. Strip them if you are passing user input through.
+     * - it is an unanchored `LIKE` over three text columns with no index, so it
+     *   is a sequential scan of your stories. Fine for thousands, not for
+     *   millions.
+     */
+    readonly q?: string;
+    /**
+     * Keep only stories at or above this importance. Also top-level.
+     *
+     * Sent through Ruby's `String#to_i`, which does NOT raise: `"high"` becomes
+     * `0` and the filter silently matches everything. Pass a number and let the
+     * SDK stringify it.
+     */
+    readonly minImportance?: number;
+    /**
+     * `"recent"` orders by `last_seen_at` descending. Anything else - including
+     * omitting it - orders by `importance` descending, then `last_seen_at`
+     * descending. There is no third value and no ascending variant.
+     *
+     * If you ALSO pass {@link PageParams.order}, both apply and yours wins: the
+     * controller appends its ordering after the list DSL has applied
+     * `modifiers[order]`, so your column becomes the primary sort key and the
+     * controller's becomes the tie-breaker. That is the opposite of what the
+     * parameter names suggest.
+     */
+    readonly sort?: "recent" | "importance";
+}
+/**
+ * `GET /intel_articles` and friends: the stories the pipeline built.
+ *
+ * Read-only plus a delete. There is no create and no update route -
+ * `IntelArticle#creatable_by?` and `#updatable_by?` both return `false`
+ * unconditionally, and the route is `only: [:index, :show, :destroy]`. Stories
+ * come from `Intel::ArticleBuilder`, never from a client.
+ */
+export declare class IntelArticlesNamespace extends Resource {
+    /**
+     * `GET /intel_articles` - your stories, most important first.
+     *
+     * Ordering is the controller's, not yours by default: `importance DESC,
+     * last_seen_at DESC`, or `last_seen_at DESC` alone with `sort: "recent"`.
+     * See {@link ListIntelArticlesParams.sort} for what happens when you pass
+     * `order` as well - it is not what the names imply.
+     *
+     * Filter keys this controller declares for `search` / `exactSearch`:
+     * `title`, `summary`, `category`, `importance`, `enriched`, plus the
+     * inherited `id`, `created_at`, `updated_at`. Anything else is
+     * `400 "Unknown search filter: x"` - fail-closed, never a wider result. The
+     * free-text and importance filters are top-level instead: `q` and
+     * `minImportance`.
+     *
+     * **Cost.** Every row runs its own `COUNT` for
+     * {@link IntelArticle.n_sources}. Keep `pageSize` in the tens, not at 500.
+     *
+     * The response carries an `ETag` and can answer `304` - except when
+     * `random` is set, which short-circuits `resources_stale?`.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     * @throws {OmsApiError} 403 `"Intel access is restricted."` for a signed-in
+     *   account outside the allowlist; 400 for an unrecognised filter key.
+     */
+    list(params?: ListIntelArticlesParams, options?: RequestOptions): Promise<Paginated<IntelArticle>>;
+    /**
+     * `GET /intel_articles/:id` - one story with its body, its sources, its
+     * related stories and the reports that cited it.
+     *
+     * The `:extended` view, so it is a strict superset of the listing row. All
+     * four extras are inlined without paging; see {@link IntelArticleDetail}.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"` when the id is not one of
+     *   yours - the lookup is `viewable_by(Current.user).find_by(id:)`, so
+     *   somebody else's story is indistinguishable from a typo, which is the
+     *   point.
+     */
+    get(id: Id, options?: RequestOptions): Promise<IntelArticleDetail>;
+    /**
+     * `DELETE /intel_articles/:id` - drops a story. `204`, empty body.
+     *
+     * The story's links to items are removed with it (`dependent: :destroy` on
+     * `intel_article_sources`), but the {@link IntelItem} rows themselves SURVIVE
+     * - they belong to the source, not to the story. They are also still marked
+     * `processed_at`, so deleting a story does not make the pipeline rebuild it.
+     * This is a hide, not an undo.
+     *
+     * @throws {OmsApiError} 404 when the story is not yours. 401
+     *   `"You are not authorized to destroy this resource"` cannot happen here -
+     *   `destroyable_by?` is `user == self.user` and the lookup already scoped it
+     *   - but note the API's habit of answering 401 rather than 403 for a failed
+     *   authorisation check, which the scripts routes DO hit.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}

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

@@ -0,0 +1,135 @@
+/** Intel config: the per-user pipeline settings. */
+import { Resource } from "../../../http";
+import type { Id, RequestOptions, Timestamp } from "../../../types";
+/**
+ * The only keys {@link IntelConfig.prompts} accepts.
+ *
+ * Any other key fails the whole `PATCH` with
+ * `400 "Prompts unknown keys: <the offenders>"`. A key that is present but
+ * empty is not the same as an absent one: absent means "use the platform
+ * default", present-and-empty means the pipeline gets an empty prompt.
+ */
+export declare const INTEL_PROMPT_KEYS: readonly ["build", "enrich_plan", "enrich_actors", "enrich_synth", "report"];
+/** One overridable prompt in the analysis pipeline. */
+export type IntelPromptKey = (typeof INTEL_PROMPT_KEYS)[number];
+/**
+ * The per-user knobs on the analysis pipeline. One row per user, created on
+ * demand - see {@link IntelConfigNamespace.get}.
+ */
+export interface IntelConfig {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /**
+     * Free text telling the classifier what "important" means for you. `null`
+     * falls back to the platform default. This is the single highest-leverage
+     * field here: everything else is a threshold applied to the score this
+     * produces.
+     */
+    readonly rubric: string | null;
+    /**
+     * Prompt overrides, keyed by {@link IntelPromptKey}. `{}` means "platform
+     * defaults everywhere"; a key present means that one stage is overridden.
+     *
+     * Nullable at the database level even though it defaults to `{}`.
+     */
+    readonly prompts: Partial<Record<IntelPromptKey, string>> | null;
+    /** LLM for the story-building pass. `null` uses the platform default. */
+    readonly build_model: string | null;
+    /** LLM for report generation. `null` uses the platform default. */
+    readonly report_model: string | null;
+    /** Stories below this importance are left out of reports. 0-10, default 4. */
+    readonly report_min_importance: number;
+    /**
+     * Stories below this importance are never web-enriched. 0-10, default 6.
+     *
+     * Lowering it does not enrich the backlog quickly: the job does three
+     * stories per run, highest importance first.
+     */
+    readonly enrich_min_importance: number;
+    /**
+     * Master switch for the enrichment pass. `false` leaves every story at
+     * `enriched: false` and `details: null` for ever.
+     */
+    readonly web_search: boolean;
+    /**
+     * How many {@link IntelSource} rows you may own. 1-500, default 50.
+     *
+     * Enforced on CREATE only (`validate :within_source_quota, on: :create`), so
+     * lowering it below your current count does not delete anything - it just
+     * stops the next create with `400 "Source limit reached (N)"`.
+     */
+    readonly max_sources: number;
+}
+/**
+ * Arguments for {@link IntelConfigNamespace.update}.
+ *
+ * Every key is optional and only the keys you send are written -
+ * `assign_attributes` over a permitted hash - so this is a genuine partial
+ * update, unlike {@link UpdateIntelSourceInput.config}.
+ */
+export interface UpdateIntelConfigInput {
+    readonly rubric?: string | null;
+    /**
+     * REPLACES the whole prompts object. Same trap as
+     * {@link UpdateIntelSourceInput.config}: it is one JSON column, so a partial
+     * object drops the keys you left out. Spread the current value.
+     *
+     * Only {@link INTEL_PROMPT_KEYS} are accepted; anything else fails the whole
+     * request with a 400 naming the offenders.
+     */
+    readonly prompts?: Partial<Record<IntelPromptKey, string>>;
+    readonly buildModel?: string | null;
+    readonly reportModel?: string | null;
+    /** 0-10. Outside the range is a 400, not a clamp. */
+    readonly reportMinImportance?: number;
+    /** 0-10. Outside the range is a 400, not a clamp. */
+    readonly enrichMinImportance?: number;
+    readonly webSearch?: boolean;
+    /** 1-500. Outside the range is a 400, not a clamp. */
+    readonly maxSources?: number;
+}
+/**
+ * `/intel_config` - the per-user pipeline settings.
+ *
+ * A Rails SINGULAR resource (`resource :intel_config`), so the path has no id
+ * and there is no listing: `GET /intel_config` and `PATCH /intel_config` are
+ * the whole surface. Both act on the caller's own row and there is no way to
+ * address anybody else's.
+ */
+export declare class IntelConfigNamespace extends Resource {
+    /**
+     * `GET /intel_config` - your settings.
+     *
+     * **This read WRITES.** The controller calls `IntelConfig.for(Current.user)`,
+     * which is `find_or_create_by!`, so a first call inserts the row with the
+     * column defaults and returns it. Consequences worth knowing: it is not safe
+     * to fire at high frequency (two concurrent first calls race on the unique
+     * index and one raises), the response is a `200` even when it just created
+     * something, and `created_at` on a "read" can be now.
+     *
+     * @throws {OmsApiError} 403 `"Intel access is restricted."` outside the
+     *   allowlist - checked before the row is created, so a refused caller does
+     *   not leave a row behind.
+     */
+    get(options?: RequestOptions): Promise<IntelConfig>;
+    /**
+     * `PATCH /intel_config` - changes settings. Answers with the whole row.
+     *
+     * A genuine partial update for the scalar fields, and a whole-object replace
+     * for `prompts` - see {@link UpdateIntelConfigInput.prompts}.
+     *
+     * The route also accepts `PUT`, and it means exactly the same thing: Rails
+     * maps both onto `update` and the controller does not read the verb. There is
+     * no "replace the whole config" call.
+     *
+     * Failures are a `400` whose body is ONE sentence, not a field map:
+     * `ApplicationRecord#error_messages` is `errors.full_messages.to_sentence`,
+     * so several violations arrive joined by commas and "and". Parse it for
+     * humans, not for code.
+     *
+     * @throws {OmsApiError} 400 for a threshold outside `0..10`, a `max_sources`
+     *   outside `1..500`, or a `prompts` key outside {@link INTEL_PROMPT_KEYS}.
+     */
+    update(input: UpdateIntelConfigInput, options?: RequestOptions): Promise<IntelConfig>;
+}